Gmail

Through the Gmail API RUNOS reads mails from a Google account, without a mail program: search unread mails, fetch their details and mark them as read. To send through Gmail, use the SMTP action.

Once: set up access

Google requires your own OAuth application:

1. In the Google Cloud Console create a project and enable the Gmail API.
2. Set up the OAuth consent screen and add your Google account as a test user.
3. Under Credentials create an OAuth client ID of type Desktop app. Note the client ID and client secret.
4. In RUNOS: Connectors → New → template Gmail API. Name the connector Gmail, enter Client ID and Client secret and save.
5. Sign in with browser and confirm access.

The template requests the gmail.send and gmail.readonly permissions. To mark mails as read, add https://www.googleapis.com/auth/gmail.modify to the Scopes and sign in again. More under OAuth2.

Fetch unread mails

{
  "Type": "HttpRequest",
  "Name": "Unread",
  "Parameters": {
    "Url": "https://gmail.googleapis.com/gmail/v1/users/me/messages",
    "Connector": "Gmail",
    "QueryParameters": { "q": "is:unread has:attachment", "maxResults": "20" }
  }
}

q understands the same search terms as Gmail’s search box. The response contains a list with an id per mail in Body.messages. Read the details per mail in a Loop:

{
  "Type": "Loop",
  "Name": "EachMail",
  "Parameters": {
    "Items": "{{Unread.Response.Body.messages}}",
    "Do": [
      {
        "Type": "HttpRequest",
        "Name": "ReadMail",
        "Parameters": {
          "Url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/{{item.id}}",
          "Connector": "Gmail",
          "QueryParameters": { "format": "metadata", "metadataHeaders": "Subject" }
        }
      }
    ]
  }
}

Inside the loop the short preview is in {{ReadMail.Response.Body.snippet}}. Check first with IF whether there are any mails at all: {{Unread.Response.Body.resultSizeEstimate}} > 0.

Mark as read

In the same iteration this action removes the UNREAD label so the mail doesn’t come back on the next fetch (requires the gmail.modify scope):

{
  "Type": "HttpRequest",
  "Name": "MarkRead",
  "Parameters": {
    "Url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/{{item.id}}/modify",
    "Method": "POST",
    "Connector": "Gmail",
    "Body": { "removeLabelIds": [ "UNREAD" ] }
  }
}

With a Time trigger (e.g. every 5 minutes) this becomes a mailbox RUNOS works through regularly.

Send a mail

To send, the Gmail API expects the complete mail as Base64. HttpRequest currently cannot build that from placeholders. So send through Gmail with the SMTP action:

1. Turn on 2-Step Verification in the Google account and create an app password under Security → App passwords.
2. Create a Basic connector GmailSmtp: user name = Gmail address, password = app password.

{
  "Type": "SMTP",
  "Name": "GmailSend",
  "Parameters": {
    "SmtpServer": "smtp.gmail.com",
    "SmtpPort": 587,
    "UseSsl": true,
    "SmtpUser": "{{connector.GmailSmtp.Username}}",
    "SmtpPassword": "{{connector.GmailSmtp.Password}}",
    "From": "{{connector.GmailSmtp.Username}}",
    "To": "customer@example.com",
    "Subject": "Your order {{InitialData.Order}}",
    "Body": "Hello,\n\nwe have received your order.",
    "Attachments": "{{FilePath}}"
  }
}

Gmail stores the mail in the Sent folder itself.