SocketLabs Email On-Demand Injection API Guide

©2009-2014 SocketLabs, Inc., Version 1.0, Last Edit: February 17, 2014

Index

Injection API Overview

API Purpose

The Email On-Demand Injection API provides users with the ability to send outbound messages through HTTP POST requests, as opposed to standard SMTP message injection which is also supported by SocketLabs Email On-Demand. The Injection API provides users with both the ability to do inline mail merges in a single HTTP POST request, and the choice of JSON or XML based on their application and business needs.This documentation is specific to injecting outbound messages over HTTPS. For information on injecting outbound messages over SMTP, please see the following Knowledge Base article. [▲]

Access & Authentication

The Injection API uses the Server ID and a per-server API key for authentication. Since authentication is a part of every message, all requests must be made using HTTPS instead of HTTP. In order to start using the Injection API, the feature must be enabled in the Control Panel and an API key (re)generated. Specifically, to enable or disable this feature and generate an API Key, select an individual server on the Control Panel, and then navigate via Configuration => Settings => Advanced Features. Please be aware that if you change any of your API credentials, any application that uses old information will stop working until it is updated with the new credentials. [▲]

Error Handling & Rate Limiting

Your application should be designed to handle failure conditions such as receiving no response or an error response from our API server. For example, the API may be down temporarily for maintenance, and calling applications should be able to handle such a situation gracefully.The Injection API has several restrictions in place to prevent too great of an email volume from being injected in a single outbound message. The specific restrictions regarding the properties of an individual injection request are as follows:

  • No more than ten (10) outbound messages in a single injection request.
  • No more than five hundred (500) recipients among all outbound messages in a single injection request. This means that there can be no more than fifty (50) recipients if the maximum number of ten (10) messages is being injected at once.
  • An individual outbound message may have no more than fifty (50) recipients regardless of other restrictions.
  • The sum of all outbound messages in a single injection request can be no more than 25MB in size.

In addition to the above restrictions on content, the following throttling rules apply to this API:

  • We allow up to five (5) injection requests per API key (or IP Address) per second.
  • We allow up to five (5) authentication failures within a two (2) minute window per API key (or IP address). When this limit is reached, additional injection requests are blocked for the remainder of the two (2) minute window.

Current restrictions with all aspects of the API may change to allow greater volume and speed in the future. [▲]

Custom Headers

In addition to the use of Mailing IDs and Message IDs used to add meta content to SMTP headers, outbound messages injected through the Injection API can include custom header fields meeting whatever needs a user may have for delivering additional information within individual messages. [▲]

Mail Merging

Perhaps the greatest advantage of the Injection API is the ability to perform inline mail merges within a single request. This is accomplished by defining variables with the desired field or fields within a request, and then defining the merge values either globally or for each individual recipient. These variables can be named freely, with the one exception being the reserved word ‘DeliveryAddress‘. This value must exist for every recipient in the PerMessage component of the mail merge, and is used to define the address of each recipient of the final mail merge.Through the use of inline mail merging, a single injection can send a completely customized outbound SMTP message and header to many recipients at once. Subject lines, header meta data, message body, and more — there is no limit to the customization that can be performed through such a merge. [▲]

Release Notes

Version 1.0, December 2012

  • Initial release.

email (injection request)

Inject one or more customized outbound messages to the Email On-Demand system.

URL:

https://inject.socketlabs.com/api/v1/email

Format:

JSON or XML

HTTP Method:

POST

Request Data Structure

A request consists of the following data structure in either JSON or XML:

Request Data Structure (JSON)

{
    "ServerId": "String",
    "ApiKey": "String",
    "Messages": [{
        "To": [{
            "EmailAddress": "String",
            "FriendlyName": "String"
        }],
        "From": {
            "EmailAddress": "String",
            "FriendlyName": "String"
        },
        "Subject": "String",
        "TextBody": "String",
        "HtmlBody": "String",
        "MailingId": "String",
        "MessageId": "String",
        "Charset": "String",
        "CustomHeaders": [{
            "Name": "String",
            "Value": "String"
        }],
        "Cc": [{
            "EmailAddress": "String",
            "FriendlyName": "String"
        }],
        "Bcc": [{
            "EmailAddress": "String",
            "FriendlyName": "String"
        }],
        "ReplyTo": {
            "EmailAddress": "String",
            "FriendlyName": "String"
        },
        "Attachments": [{
            "Name": "String",
            "Content": "String",
            "ContentId": "String",
            "ContentType": "String",
            "CustomHeaders": [{
                "Name": "String",
                "Value": "String"
            }]            
        }],
        "MergeData": {
            "PerMessage": [[{
                "Field": "String",
                "Value": "String"
            }]],
            "Global": [{
                "Field": "String",
                "Value": "String"
            }]
        }
    }]
}

Request Data Structure (XML)

<PostBody>
    <ApiKey>String</ApiKey>
    <ServerId>Integer</ServerId>
    <Messages>
        <EmailMessage>
            <To>
                <Address>
                    <EmailAddress>String</EmailAddress>
                    <FriendlyName>String</FriendlyName>
                </Address>
            </To>
            <From>
                <EmailAddress>String</EmailAddress>
                <FriendlyName>String</FriendlyName>
            </From>
            <Subject>String</Subject>
            <TextBody>String</TextBody>
            <HtmlBody>String</HtmlBody>
            <MailingId>String</MailingId>
            <MessageId>String</MessageId>
            <Charset>String</Charset>
            <CustomHeaders>
                <CustomHeader>
                    <Name>String</Name> 
                    <Value>String</Value> 
                </CustomHeader>
            </CustomHeaders>
            <Cc>
                <Address>
                    <EmailAddress>String</EmailAddress> 
                    <FriendlyName>String</FriendlyName> 
                </Address>
            </Cc>
            <Bcc>
                <Address>
                    <EmailAddress>String</EmailAddress> 
                    <FriendlyName>String</FriendlyName> 
                </Address>
            </Bcc>
            <ReplyTo>
                <EmailAddress>String</EmailAddress> 
                <FriendlyName>String</FriendlyName> 
            </ReplyTo>
            <Attachments>
                <Attachment>
                    <Name>String</Name> 
                    <ContentType>String</ContentType> 
                    <Content>Base64EncodedData</Content> 
                    <CustomHeaders>
                        <CustomHeader>
                            <Name>String</Name> 
                            <Value>String</Value> 
                        </CustomHeader>
                    </CustomHeaders>
                    <ContentId>String</ContentId> 
                </Attachment>
            </Attachments>
            <MergeData>
                <PerMessage>
                    <ArrayOfMergeRow>
                        <MergeRow>
                            <Field>String</Field> 
                            <Value>String</Value> 
                        </MergeRow>
                    </ArrayOfMergeRow>
                </PerMessage>
                <Global>
                    <MergeRow>
                        <Field>String</Field> 
                        <Value>String</Value> 
                    </MergeRow>
                </Global>
            </MergeData>
        </EmailMessage>
    </Messages>
</PostBody>

Following are descriptions of the parameters from the above data structures. [▲]

Request Parameters

The top-level fields are:

ApiKey
The per-server API key used to authenticate.
Messages
An array of one (1) or more EmailMessage instances.
ServerId
The id of the virtual server being used.

The sub-fields within each entry of the Messages array are:

Message.Attachments
An array of attached content blobs, such as images, documents, and other binary files.
Message.Attachments.Content
The BASE64 encoded string containing the contents of an attachment.
Message.Attachments.ContentId
When set, used to embed an image within the body of an email message.
Message.Attachments.ContentType
The MIME type of an attachment.
Message.Attachments.CustomHeaders
An array of header field data stored in Name/Value pairs.
Message.Attachments.Name
The name of an attached file.
Message.Bcc
An array of recipient EmailAddress/FriendlyName value pairs representing the BCC’d recipients of an email message.
Message.Cc
An array of recipient EmailAddress/FriendlyName value pairs representing the CC’d recipients of an email message.
Message.CharSet
The charset name to be used when creating the message. Default is UTF8.
Message.CustomHeaders
An array of header field data stored in Name/Value pairs.
Message.From
The EmailAddress/FriendlyName value pair for the sender of the message.
Message.HtmlBody
The HTML portion of the message body.
Message.MailingId
SocketLabs header used to track batches of messages.
Message.MergeData
Data storage for the inline Merge feature.
Message.MergeData.PerMessage
An two dimensional (2D) array of Field/Value pairs, used to define merge field data for each message. Variables can be freely named, with the exception of a single reserved word, ‘DeliveryAddress‘, which defines the recipient of the current message.
Message.MergeData.Global
An array of Field/Value pairs, used to define merge field data for all messages in the injection.
Message.MessageId
SocketLabs header used to tag individual messages.
Message.ReplyTo
The EmailAddress/FriendlyName value pair to be used if replying to this email message.
Message.Subject
The subject line of the email address.
Message.TextBody
The text (non-HTML) portion of the message body.
Message.To
An array of recipient EmailAddress/FriendlyName value pairs representing the recipients of an email message.

Addresses are represented by a pair of fields used together throughout this data structure:

*.EmailAddress
An email address string such as ‘foo@example.com’.
*.FriendlyName
An alias for an email address.

Custom headers are represented by a pair of fields used together in a CustomHeaders array:

*.Name
The name of the header field to be added, such as ‘Content-Type’.
*.Value
The value of the header field to be added, such as ‘application/json’.

Following are multiple examples of requests in JSON and XML. [▲]

Request Examples

Request Example – Simple (JSON)

{
    "ServerId": "YOUR SERVER ID HERE",
    "ApiKey": "YOUR API KEY HERE",
    "Messages": [{
        "MailingId": null,
        "MessageId": null,
        "MergeData": null,
        "Subject": "Email subject line for this example.",
        "TextBody": "The text portion of the message.",
        "HtmlBody": "<h1>The HTML portion of the message</h1><br/><p>A paragraph.</p>",
        "CustomHeaders": null,
        "To": [{
            "EmailAddress": "to@example.com",
            "FriendlyName": null
        }],
        "Cc": null,
        "Bcc": null,
        "From": {
            "EmailAddress": "from@example.com",
            "FriendlyName": "From Address"
        },
        "ReplyTo": null,
        "Charset": null,
        "Attachments": null
    }]
}

Request Example – Simple (XML)

<PostBody>
    <ApiKey>YOUR API KEY HERE</ApiKey>
    <ServerId>YOUR SERVER ID HERE</ServerId>
    <Messages>
        <EmailMessage>
            <To>
                <Address>
                    <EmailAddress>to@example.com</EmailAddress>
                    <FriendlyName></FriendlyName>
                </Address>
            </To>
            <From>
                <EmailAddress>from@example.com</EmailAddress>
                <FriendlyName>From Address</FriendlyName>
            </From>
            <Subject>Email subject line for this example.</Subject>
            <TextBody>The text portion of the message.</TextBody>
            <HtmlBody><h1>The HTML portion of the message</h1></HtmlBody>
        </EmailMessage>
    </Messages>
</PostBody>

Request Example – Complex Merge (JSON)

{
    "ServerId": "YOUR SERVER ID HERE"
    "ApiKey": "YOUR API KEY HERE",
    "Messages": [{
        "MailingId": "HR-017",
        "MessageId": "0000001928",
        "MergeData": null,
        "Subject": "Welcome to The ABC Company!",
        "TextBody": "Welcome to The ABC Company, new employee!",
        "HtmlBody": "<h1>Welcome to The ABC Company, new employee!</h1>",
        "CustomHeaders": [{
            "Name": "Internal-Email-Type",
            "Value": "HR/New Employee"
        }],
        "To": [{
            "EmailAddress": "bob@example.com",
            "FriendlyName": "Robert Smith"
        },
        {
            "EmailAddress": "alice@example.com",
            "FriendlyName": "Alice White"
        },
        {
            "EmailAddress": "christine@example.com",
            "FriendlyName": "Christine Johnson"
        }],
        "Cc": [{
            "EmailAddress": "hr@example.com",
            "FriendlyName": "HR Department"
        }],
        "Bcc": [{
            "EmailAddress": "logging@example.com",
            "FriendlyName": "Email Logging Account"
        }],
        "From": {
            "EmailAddress": "donotreply@example.com",
            "FriendlyName": "From Address"
        },
        "ReplyTo": {
            "EmailAddress": "hr@example.com",
            "FriendlyName": "HR Department"
        },
        "Charset": "us-ascii",
        "Attachments": [{
            "Name": "CompanyContacts.txt",
            "ContentType": "text/plain",
            "Content": "VEhJUyBJUyBUSEUgQVRUQUNITUVOVA==",
            "CustomHeaders": null,
            "ContentId": null
        }]
    },
    {
        "MailingId": "%%MailingId%%",
        "MessageId": "%%CUSTOM-SERIAL-NUMBER-ID%%",
        "MergeData": {
            "PerMessage": [[{
                "Field": "DeliveryAddress",
                "Value": "bob@example.com"
            },
            {
                "Field": "RecipientName",
                "Value": "Robert Smith"
            },
            {
                "Field": "SeniorEmployeeName",
                "Value": "Elizabeth Johnson"
            },
            {
                "Field": "CUSTOM-SERIAL-NUMBER-ID",
                "Value": "0000001005"
            }],
            [{
                "Field": "DeliveryAddress",
                "Value": "alice@example.com"
            },
            {
                "Field": "RecipientName",
                "Value": "Alice White"
            },
            {
                "Field": "SeniorEmployeeName",
                "Value": "Elizabeth Johnson"
            },
            {
                "Field": "CUSTOM-SERIAL-NUMBER-ID",
                "Value": "0000001006"
            }],
            [{
                "Field": "DeliveryAddress",
                "Value": "christine@example.com"
            },
            {
                "Field": "RecipientName",
                "Value": "Christine Johnson"
            },
            {
                "Field": "SeniorEmployeeName",
                "Value": "Gary Brown"
            },
            {
                "Field": "CUSTOM-SERIAL-NUMBER-ID",
                "Value": "0000001007"
            }]],
            "Global": [{
                "Field": "MailingId",
                "Value": "HR-018"
            }]
        },
        "Subject": "Employee mentorship program information.",
        "TextBody": "%%RecipientName%%, you have been paired with
                     %%SeniorEmployeeName%% as part of our mentorship program!",
        "HtmlBody": "<h1>%%RecipientName%%, you have been paired with
                     %%SeniorEmployeeName%% as part of our mentorship program!</h1>",
        "CustomHeaders": null,
        "To": [{
            "EmailAddress": "%%DeliveryAddress%%",
            "FriendlyName": "%%RecipientName%%"
        }],
        "Cc": null,
        "Bcc": null,
        "From": {
            "EmailAddress": "hr@example.com",
            "FriendlyName": "HR Department"
        },
        "ReplyTo": null,
        "Charset": null,
        "Attachments": null
    }]
}

email (injection response)

Information pertaining to the success or failure of outbound messages injected by an email POST request.

Format:

JSON or XML

Response Data Structure

A response consists of the following data structure in either JSON or XML:

Response Data Structure (JSON)

{
    "ErrorCode": "String",
    "TransactionReceipt": "String",
    "MessageResults": [{
        "Index": "Integer",
        "ErrorCode": "String",
        "AddressResults": [{
            "EmailAddress": "String",
            "Accepted": "Boolean",
            "ErrorCode": "String"
        }]
    }]
}

Response Data Structure (XML)

<PostResponse>
    <ErrorCode>String</ErrorCode>
    <TransactionReceipt>String</TransactionReceipt>
    <MessageResults>
        <MessageResult>
            <Index>Integer</Index>
            <ErrorCode>String</ErrorCode>
            <AddressResults>
                <AddressResult>
                    <EmailAddress>String</EmailAddress>
                    <Accepted>Boolean</Accepted>
                    <ErrorCode>String</ErrorCode>
                </AddressResult>
            </AddressResults>
        </MessageResult>
    </MessageResults>
</PostResponse>

Following are descriptions of the parameters from the above data structures. [▲]

Response Parameters

The top-level fields are:

ErrorCode
The success or failure details of the overall injection request. See the appendix at the bottom of this document for a complete list of values.
MessageResults
An array of message result objects for messages that failed or have bad recipients. If there were no errors this response is empty.
MessageResults.item.AddressResults
An array of AddressResult objects that contain the status of each address that failed. If no messages failed this array is empty.
MessageResults.item.AddressResults.Accepted
A true or false value indicating whether or not the message was deliverable.
MessageResults.item.AddressResults.EmailAddress
The recipient address which generated the warning or error.
MessageResults.item.AddressResults.ErrorCode
The reason for message delivery failure when an error occurs on the address-level. See the appendix at the bottom of this document for a complete list of values.
MessageResults.item.ErrorCode
The reason for message delivery failure when an error occurs on the message-level. See the appendix at the bottom of this document for a complete list of values.
MessageResults.item.Index
The index of the message that this response represents from the original array posted.
TransactionReceipt
A unique key generated if an unexpected error occurs during injection that can be used by SocketLabs support to troubleshoot the issue.

Following are multiple examples of responses in JSON and XML. [▲]

Response Examples

Response Example – Successful (JSON)

{
    "ErrorCode": "Success",
    "MessageResults": []
}

Response Example – Successful (XML)

<PostResponse>
    <ErrorCode>Success</ErrorCode>
    <MessageResults></MessageResults>
</PostResponse>

Response Example – Error (JSON)

{
    "ErrorCode": "Warning",
    "MessageResults": [{
        "Index": 0,
        "ErrorCode": "InvalidFromAddress",
        "AddressResults": null
    }],
    "TransactionReceipt": null
}

Response Example – Error (XML)

<PostResponse>
    <ErrorCode>Warning</ErrorCode>
    <TransactionReceipt></TransactionReceipt>
    <MessageResults>
        <MessageResult>
            <Index>0</Index>
            <ErrorCode>InvalidFromAddress</ErrorCode>
            <AddressResults></AddressResults>
        </MessageResult>
    </MessageResults>
</PostResponse>

Appendix

Delivery Return Codes

The following failure codes may be returned from the outbound email injection request inside of the PostResponse return object.

Return codes within the PostResponse object, specifying the status of
the injection request:

    Success - No error.
    Warning – There were one or more failed messages and/or recipients.
    AccountDisabled - The account has been disabled.
    InternalError - Internal server error. (Please report to SocketLabs
                    support if encountered.)
    InvalidApiKey - API key is invalid.
    InvalidData - PostBody parameter does not have a valid structure, or
                  contains invalid or missing data.
    NoMessages - There were no messages to inject included in the request.
    EmptyMessage - One or more messages have insufficient content to process.
    OverQuota - Rate limit exceeded.
    TooManyErrors - Authentication error limit exceeded.
    TooManyMessages - Too many messages in a single request.
    TooManyRecipients - Too many recipients in a single message.
    NoValidRecipients - A merge was attempted, but there were no valid recipients.

Return codes within the MessageResult object, specifying the status of a
specific message:

    Warning - The message has one or more bad recipients.
    InvalidAttachment - The message has one or more invalid attachments.
    MessageTooLarge - The message was larger than the allowed size.
    EmptySubject - This message contained an empty subject line, which is not allowed.
    EmptyToAddress - This message does not contain a To address.
    InvalidFromAddress - This message does not contain a valid From address.
    NoValidBodyParts - This message does not have a valid text HTML body specified.
    NoValidRecipients - There are no valid addresses specified as message recipients.
    InvalidMergeData - The included merge data does not follow the API specification.

Return codes within the AddressResult object, specifying the status of a
specific recipient:

    InvalidAddress - The address did not meet specification requirements.

Downloadable Samples

Injection API sample code can be downloaded from github: http://github.com/socketlabs/ [▲]