Artisan IMG > Gmail (gmail) (a73616ca-6c58-48ad-a422-7f4fd5b0a792)
Artisan IMG > Gmail (gmail) (a73616ca-6c58-48ad-a422-7f4fd5b0a792)

Gmail
4.0

Fast, searchable email with less spam.

Overview
Copy

Use the Tray.io Gmail connector to list, send and download emails as well as change system preferences.

API Information
Copy

The Gmail connector has the following Base URL: https://www.googleapis.com/gmail/v1. More information can be found on their main API documentation (v1) site. Details regarding their API limitations can be found here.

Authentication
Copy

Before authenticating this Google connector, you will need to whitelist the Tray.io Google authentication app. Please follow the instructions here before continuing with the authentication process.

Also note that the connector does not support personal gmail accounts. You should have a gmail for business

Once this is done, you can click on the New Authentication button:

A window appears displaying what scopes will be requested for your account. Tick accordingly and continue.

After being redirected to Google, click on the Allow button found at the bottom of the window.

The authentication process has been completed and the connector can now be used.

Gmail Trigger
Copy

The Gmail trigger allows you to receive notifications and trigger workflows when given events occur associated with the selected trigger operation.

Trigger Operations available:
Copy

  • Webhook

    • Tracks the version of your mailbox and triggers the workflow when it changes. You can then use the List history operation within the Gmail connector to find out what change actually happened.

  • On Event

    • Choose the event type from the properties panel.

Authentication Setup
Copy

Select the Gmail trigger. In the Gmail trigger properties panel to the right of the builder, click on the Authenticate tab and the Add new authentication button.

This will result in a Tray.io authentication pop-up modal. The first page will ask you to name your authentication and select the type of authentication you wish to create ('Personal' or 'Organisational').

The next page asks you for your Service account email, Private key and Subject email amongst other permissions. You only need to use these if you wish to use the operation Send as alias (in the Gmail connector).

They are otherwise not mandatory. The rest of the permissions should only be selected if your use case requires them.

Important Trigger Notes
Copy

Trigger Failure
Copy

If your Gmail trigger is failing you may receive an error message similar to this:

1
{
2
"message": "Events are failing to be delivered. Please try re-initializing your workflow or re-creating your subscription. Reason: The request is unauthorized"
3
}

It is probably because of one of the following reasons:

  • An authentication was revoked.

    • You received an unauthorised/forbidden response.

  • The mailbox in question no longer exists.

    • You received a "Not found error".

The best way to mitigate any trigger failures as always, is with an (alerting) error handling workflow.

The failed payload should be collected and you notified immediately - via Slack or email etc. That way you will be able to resolve the issue immediately with minimal inconvenience.

More information and examples on how to build this kind of workflow check out the docs here.

Include Full Message
Copy

Please note that if the message you are referring to no longer exists then the trigger won't be able to fetch the full message body.

You will only get the additional fields if the message is still in your mailbox

Notes on using Gmail
Copy

Sending one email to multiple inboxes
Copy

There may be an occasion where you will wish to send one email to multiple email addresses.

In this use case you have three options to choose from. You don't need to know the exact number of email addresses you will need to send your email to, for any of them before setting up.

This is based on the fact that the list of multiple email addresses you create will be returned as an array and array can be populated with one or several items.

Your options are as follows:

  1. Via the Property Panel: Pass the data direct to the highest property of the properties panel - as long as you format the data correctly.

  2. Use Connector Helpers: If you pass an array to either of them then they will return a string version of the listed email address.

  3. JSONata: Solution:

    1
    $$ @ $data.{
    2
    "to": $data.custom."Primary Customer Contact" = true ? $data.email : null
    3
    }[to != null]

Downloading file attachments
Copy

If you want to download an attachment from an email note that the download will get saved in a file format

You will need to use the File helper to download the attachment properly (and in the desired format).

Example 1 - Sending an email
Copy

This example will walkthrough how to send an email using the Gmail connector.

The first step is to select the Send email operation.

Here, a subject and an email body has been defined. This has been done using the subject and body input fields.

The next step is to configure the address that will be sending the email, and the address that will be receiving the email.

The email is now ready to be sent. To do so, the workflow is ran and as can be seen it has been successful in sending the email.

Below, you can also see the email that was sent on an email client.