Email Engagement using the API

Send Bulk Email

Prerequisites

Validate an email id under “Account”, “Email”, “IDs”
1. Retrieve the UUID from the URL to be used when creating the engagement activity. See the “email-id” relationship below example.
Create and retrieve an API Token under “Developer”, “API Tokens”
1. Use as basic authorization header, example below
2. Construct string separated by a colon “user:pass” and then base64 encode. See: https://tools.ietf.org/html/rfc7617
Retrieve account key from “Account”, “Settings”, “General” (e.g., “firstbank”)
1. Use as `X-Account-Key` header

API Documentation

Creating an email engagement requires the following:

Create an email template: https://omnigage.docs.apiary.io/#reference/email-resources/email-template-collection/create-email-template
1. Note: Retrieve the email template ID to be used when creating the activity.
Create an engagement: https://omnigage.docs.apiary.io/#reference/engagement-resources/engagement-collection/create-engagement
1. Note: Retrieve the engagement ID to be used when creating the activity and envelopes.
Create an activity: https://omnigage.docs.apiary.io/#reference/engagement-resources/activity-collection/create-activity
1. Note: Requires the engagement ID and email template ID.
Create envelopes: https://omnigage.docs.apiary.io/#reference/engagement-resources/envelope-collection/create-envelope
1. Note: See the example below for creating bulk requests using headers `Content-Type` and `Accept` of `application/vnd.api+json; ext=bulk`

Example Requests

1. Create an Email Template

POST /api/v1/email-templates
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z...
{
    "data": {
        "type": "email-templates",
        "attributes": {
            "subject": "Weekly Specials",
            "body": "Hello {{first-name}},<br /><br /><strong>Supports HTML</strong>{{unsubscribe-link}}"
        }
    }
}

2. Create Engagement

POST /api/v1/engagements
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z...
{
    "data": {
        "type": "engagements",
        "attributes": {
            "name": "Email Blast",
	    "direction": "outbound"
        }
    }
}

3. Create an Activity

POST /api/v1/activities
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z...
{
    "data": {
        "type": "activities",
        "attributes": {
            "name": "Email Blast",
            "kind": "email"
        },
        "relationships": {
            "engagement": {
                "data": {"type": "engagements", "id": "cu8Eo9RyrUsV4MXEiDZpLM"}
            },
            "email-template": {
                "data": {"type": "email-templates", "id": "iDZpLM8Eo9RyrUsV4MXE"}
            },
            "email-id": {
                "data": {"type": "email-ids", "id": "iwXgSh6KPiF7QPd9mAorSp"}
            }
        }
    }
}

4. Create Envelopes

POST /api/v1/envelopes
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z...
Content-Type: application/vnd.api+json; ext=bulk
Accept: application/vnd.api+json; ext=bulk
{
    "data": [{
        "type": "envelopes",
        "attributes": {
            "email-address": "alexander.bell@bell-labs.com",
            "meta": {
                "first-name": "Alexander",
                "last-name": "Bell"
            }
        },
        "relationships": {
            "engagement": {
                "data": {"type": "engagements", "id": "yrbCdxqV2ZMdQBCszhA7TZ"}
            }
        }
    },
    {
        "type": "envelopes",
        "attributes": {
            "email-address": "michael.morgan@omnigage.com",
            "meta": {
                "first-name": "Michael",
                "last-name": "Morgan"
            }
        },
        "relationships": {
            "engagement": {
                "data": {"type": "engagements", "id": "yrbCdxqV2ZMdQBCszhA7TZ"}
            }
        }
    }]
}

4. Submit Engagement for Processing

PATCH /api/v1/engagements/yrbCdxqV2ZMdQBCszhA7TZ
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z...
{
   "data":{
      "id": "yrbCdxqV2ZMdQBCszhA7TZ",
      "type": "engagements",
      "attributes": {
         "status": "scheduled",
         "delivery-type": "immediately"
      }
   }
}