RESTFUL API - GATORMAIL

For developers that want to integrate to the Gator marketing platform then the RESTFUL API is available through your SSO (single sign on) account using oAuth2. 

The full API details can be found at https://api.communigator.co.uk

 

oAuth Token and Secret

To retrieve an oauth token you will need to pass an Authorization header to the token endpoint in the following format:

Authorization: Basic [ENCODED_CLIENT+SECRET]

Where [ENCODED_CLIENT+SECRET] is your client id and client secret separated by a colon and Base64 encoded.

Please contact support or your account mgr to gain access to your clientid and secret. 

 

Example Request

Here is an example request (you will need to replace [SSO_USERNAME] and [SSO_PASSWORD] with your CommuniGator single sign on credentials and [ENCODED_CLIENT+SECRET] with your base64 encoded client id and secret).

curl -X POST http://oauth.communigator.co.uk/core/connect/token -H "Authorization: Basic [ENCODED_CLIENT+SECRET]" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=[SSO_USERNAME]&password=[SSO_PASSWORD]&scope=openid%20GatorMailApi"

This will return an access token in the below format:

{"access_token":"hJJ0eXASDSsdsdKV1Q....","expires_in":3600,"token_type":"Bearer"}

 

Using the Access Token

You can then use this access token to call any of the GatorMail end points in the API documentation: https://communigator.github.io/API-Documentation/

To do so call the desired endpoint and pass along an Authorization header like so:

curl -X GET https://api.communigator.co.uk/mail/coinsglobal_testlz/campaign/1/100 -H "Authorization: Bearer [ACCESS_TOKEN]" -H "Content-Type: application/json"

The tools/integration screen is unrelated to accessing the API and is only used if you have one of our CRM integrations setup.

  

GatorMail Integration: Email Marketing Examples

1. Create Campaign

A campaign effectively represents an email campaign with an associated audience

https://communigator.github.io/API-Documentation/#operation/gatormail_addCampaign

 

2. Create the Audience

Audience of email contacts is called a group in GatorMail and is attached to an email campaign, the below explains how to add the group to your campaign

2.1 Add a group (storing the group id returned)

https://communigator.github.io/API-Documentation/#operation/gatormail_addGroup

2.2 Add contacts to the created group (using the group id returned in 2.1):

https://communigator.github.io/API-Documentation/#operation/gatormail_groupIncludedContactpost

2.3 Update the campaign created in step 1 with the group id returned in 2.1:

https://communigator.github.io/API-Documentation/#operation/gatormail_updateCampaign

 

3. Mappings:

GatorMail allows you to map contact fields from your 3rd party system/CRM to its own contacts.

3.1 Clear all schema entities and attributes:

https://communigator.github.io/API-Documentation/#operation/gatormail_deleteSchema

3.2 Addschema entities and attributes to GM to allow for mappings:

https://communigator.github.io/API-Documentation/#operation/gatormail_postSchemaEntityhttps://communigator.github.io/API-Documentation/#operation/gatormail_postSchemaAttribute

3.3 Check for a publish request from the user of GM after configuring the mappings schema:

https://communigator.github.io/API-Documentation/#operation/gatormail_getIntegrationRequests

3.4 After applying the schema reset the schema status to notify the user it's done:

https://communigator.github.io/API-Documentation/#operation/gatormail_getIntegrationRequestSatisfied

3.5 See if the schema mappings have been published:

https://communigator.github.io/API-Documentation/#operation/gatormail_getIntegrationRequests

3.6 If so pull them down:

https://communigator.github.io/API-Documentation/#operation/gatormail_getSchema

3.7 Mark as complete to let the GM user know:

https://communigator.github.io/API-Documentation/#operation/gatormail_getIntegrationRequestSatisfied

 

4 DataFeed:

All email campaign activity data is queued into a table and can be accessed using the following calls. These activities make up:

Email opens, clicks, downloads, unsubscribes, survey answers, bounces, event invites

4.1 If needed the client can set and get the data feed options:

https://communigator.github.io/API-Documentation/#operation/gatormail_getDatafeedOptionshttps://communigator.github.io/API-Documentation/#operation/gatormail_postDatafeedOptions

4.2 Retrieve a batch of data feed records:

https://communigator.github.io/API-Documentation/#operation/gatormail_getDatafeed

4.3 Mark them as processedwhen complete:

https://communigator.github.io/API-Documentation/#operation/gatormail_getDatafeedBatchIdentifier