The easy way to connect with the Gmail API

commits first year
The easy way to connect with the Gmail API
author Maikel Arcia, Mar 3, 2016

We have recently brought the set of API collections to connect with the Google services, to let you access an entire API through a single authorization point, with an offline and background running logic for the automatic management of the OAuth 2.0 protocol implementation provided by Google. Nevertheless, interacting with an API may be a little awkward. To use the Gmail API, for example, you have to format emails following the MIME standard, then you have to encode them in base64, and then you have to conform a JSON document following a Gmail API schema.

Hopefully you do not have to run the awkward way anymore, because the Gmail Cenit Collection is now available, a wrapper that let you send emails as easy as it can be. Try it now by following the next steps by yourself, signing up for free in Cenit.

Trying the Gmail Collection

First of all go to the Gmail Shared Collection and pull it with your Cenit account. If you do not have a Cenit account go on anyway and create one, it’s free.

pull gmail collection

Once you have successfully executed the pull action you are redirected to your Gmail Collection. Now you should follow the steps on the 'Quick Start' section of the collection readme. Two simple steps, and you will send an email with your Google account through Cenit.io, just click the links to get them done

gmail quick start

The easy way

If you continue reading your Gmail Collection readme you will get instructions to use the CenitHub API. Now you can send emails in a simple JSON format like this

            
{
  "to": "support@cenit.io",
  "subject": "Hello",
  "body": "Just to say hello!",
  "attachments": [
    {
      "filename": "file.txt",
      "data": "Sent through CenitHub API"
    }
  ]
}
            

You can try it with a CURL command

curl -H
  "Content-Type: application/json"\
  -H "X-User-Access-Key: XXXXXXX"\
  -H "X-User-Access-Token: XXXXXXXXXXXXXXXX"\
  -X POST -d '{"to":"support@cenit.io","subject":"Hello","body":"Just to say hello!","attachments":[{"filename":"file.txt","data":"Sent through Cenit.io API"}]}'\
  https://cenit.io/api/v1/mime/message

            

Just copy the CURL command from the readme (it already contains proper access headers) and run it in your console. The email in JSON format is sent to the Cenit.io API and then Cenit does all the awkward work for you. You can send emails in any format supported by the Cenit.io API, XML for example. Multiple attachments and binary data are also supported, just continue reading your collection readme to see more examples.

Because Cenit.io automatically manages your OAuth 2.0 access and refreshes tokens, you don not have to worry in the future about being authorized again. Just continue sending emails in a simple format through the Cenit.io API, until you explicitly revoke your authorization with your Cenit account or in your Google Acount configuration.

If you find an easier way to use the Gmail API please let us know, surely we can make a wrapper for that and then a very much easier way will be available for the community. In fact, we are working on several collections similar to this to let you connect with multiple APIs easy. Just check the list of Shared Collection that is available so far.

You have to know that the ability of Cenit to connect with an API is just a facility to reach a major goal, which is the integration of solutions that may involve several APIs. To accomplish that, Cenit allows the orchestration of data flows through the configuration of flows, events, data types, connectors, authorizations and so on. Inspect the rest of sections of your Gmail Collection and you will see all the configuration elements composing the collection. You can configure your own collections, test them and setup to integrate your real world solutions. The next section gives you a background of how your Gmail Collection is configured.

How it works

The workflow that sends an email through Cenit.io starts at the DATA configuration area, where the Gmail Collection defines the data types to manage email records. The MIME Message data type is defined by a JSON Schema that references the MIME Attachment file data type.

When a MIME Message is created in the administration view of the Cenit.io portal or via POST using the Cenit.io API then a creation event is fired. Events are defined in the WORKFLOW area and their main function is to trigger flows executions.

By default, your Gemail Collection defines the flow Send Created Message, which is triggered when a MIME Message is created. Every flow is associated with a translator, in this case the translator MIME To Gmail API V1 Message, which transforms the MIME Message into a JSON document that complies with the Gmail API schema. To accomplish that, the translator first invokes an algorithm to convert a message record into a RFC822 format

Then the translator encodes the result in Base64 to finally build the JSON document for the Gmail API schema.

The document is now ready to be sent to the API CONNECTORS area. The entry point to the API connection area is the webhook configured in the flow.

gmail quick start

Webhooks act like actions to be submitted via HTTP requests. Submitting a webhook requires a binding to a connection which defines the endpoint base URL to be completed with the webhook path. Such bind is established by a connection role that relates the webhook and the connection.

Connection roles define many to many relations, which means that a single flow execution can submit the same action to multiple endpoints. Your Gmail Collection by default uses only one connection role which binds to a single connection, the Gmail API v1 Oauth 2.0 HTTPS Connection. When a webhook is bound to a connection, the headers and parameters for the request are automatically conformed, including any required authorization data, and here is when the flow execution reaches the SECURITY area.

gmail quick start

The entry point to the security area is the authorization configured in the webhook or the connection. Authorizations handle credentials complying with several protocols. The Gmail Collection by default uses an Oauth 2.0 Authorization which is simply configured by selecting an OAuth client application and the respective authorization scopes. As mentioned before, the credentials are automatically handled, for the case of OAuth 2.0 the provider configuration defines a refresh token strategy that can be selected from a set of build-in strategies or it can be customized using an algorithm. Cenit.io shares a set of providers, clients and scopes that can be used to configure the authorization you need.

Once the authorization have been successfully handled, the connectors area submits the document in a request including the required authorization headers.

gmail quick start
gmail quick start

A flow execution does not end when submitting a request. The response is redirected to the workflow area where the flow can be configured to process it. In this case, the success Gmail API v1 response contains a JSON document with information about the processed message, the Gmail thread identifier, for example, which would be used for tracking the message but, surely for a future collection version.

gmail quick start
gmail quick start

What’s next

Check the list of Shared Collection that is available and try another easy way to connect with an API. Just pull a collection and play with it. Have not found the collection you are interesting in? Let us know.

For more information, please contact us by cenithub.com or send us a message to the email address support@cenit.io


Back to blog Get in touch