SocketLabs Email On-Demand Injection API Guide

©2009-2013 SocketLabs, Inc., Version 1.0, Last Edit: March 19, 2013

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 HTTP. For information on injecting outbound messages over SMTP, please see the following KB article: https://support.socketlabs.com/kb/94

Back to top

Access & Authentication

The Injection API uses the Server ID and a per-server API key for authentication. Currently, in order to use 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 => Beta 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.

Back to top

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.

Back to top

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.

Back to top

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. 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.

Back to top

Release Notes

Version 1.0, December 2012

  • Initial release.

Back to top

Method Reference

email (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

Data Structure:

A request consists of the following data structures:

PostBody :=
    ServerId [Required] : String
    ApiKey [Required] : String
    Messages [Required] : EmailMessage[]

ServerId : The id of the virtual server being used.
ApiKey : The per-server API key used to authenticate.
Messages : An array of one (1) or more EmailMessage instances.
EmailMessage :=
    To [Required] : Address[]
    From [Required] : Address
    Subject [Required] : String
    TextBody [Required*] : String
    HtmlBody [Required*] : String
    MailingId : String
    MessageId : String
    CustomHeaders : CustomHeader[]
    Cc : Address[]    
    Bcc : Address[]
    ReplyTo : Address
    Charset : String
    Attachments : Attachment[]
    MergeData : MergeData

* At least one of TextBody or HtmlBody (or both) has to exist for the request to be valid.

To : One or more Address instances defining the message recipient(s).
From: The Address instance defining the sender.
Subject : The subject line of the email message.
TextBody : The plain text payload of the email message.
HtmlBody : The HTML payload of the email message.
MailingId : SocketLabs header used to track batches of messages.
MessageId : SocketLabs header used to tag individual messages.
CustomHeaders : User-defined email header fields and values.
Cc : An array of zero or more Address instances to carbon copy the message to.
Bcc : An array of zero or more Address instances to blind-carbon-copy the message to.
ReplyTo : The Address instance representing the reply-to address.
Charset : The charset name to be used when creating the message. Default is UTF8.
Attachments : An array of zero or more Attachment instances defining attached files.
MergeData : Data storage for the inline Merge feature.
CustomHeader :=
    Name [Required] : String
    Value [Required] : String

Name : The name of the header field to be added.
Value : The value of the header field to be added.
Address :=
    EmailAddress [Required] : String
    FriendlyName : String

EmailAddress : The email address for this entry.
FriendlyName : The alias for this email address.
Attachment :=
    Name [Required] : String
    Content [Required] : String
    ContentType : String
    CustomHeaders : CustomHeader[]
    ContentId : String

Name : The name of the attached file.
Content : The BASE64 encoded string containing the contents of the attachment.
ContentType : The MIME type of the attachment.
CustomHeaders : User-defined email header fields and values.
ContentId : When set, used to embed an image and group it with the body
            part of the message.
MergeData :=
    PerMessage [Required*] : MergeRow[][]
    Global : MergeRow[]

* If MergeData is used, then PerMessage must, at a minimum, contain the
  'DeliveryRecipient' field, which specifies the recipient(s) of the
  merged message(s) and the values shown in the 'To' header field. Any values
  provided in the Cc and Bcc members are used for display in the header only.

PerMessage : Merge data for individual recipients.
Global : Merge data for all recipients.
MergeRow :=
    Field [Required] : String
    Value [Required] : String

Field : The name of the merge variable being defined.
Value : The value of the merge variable for this entry.

Following are multiple examples of requests and responses in JSON. XML requests and responses would have the same structure and contain the same data, but would understandably be encoded differently.

Request Example (Simple):

{
    "ServerId": "YOUR SERVER ID HERE",
    "ApiKey": "YOUR API KEY HERE",
    "Messages": [{
        "MailingId": null,
        "MessageId": null,
        "MergeData": null,
        "Subject": "Email subject line for SDK 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 (Merge):

{
    "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
    }]
}

Back to top

email (response)

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

Format:

JSON or XML

Data Structure:

A response consists of the following data structures:

PostResponse :=
    ErrorCode : String
    MessageResults : MessageResult[]

ErrorCode : The success or failure details of the 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.
MessageResult :=
    Index: Int
    ErrorCode: String
    AddressResults : AddressResult[]
    TransactionReceipt : String

Index : The index of the message that this response represents from the original
    array posted.
ErrorCode : The reason for message failure. See the appendix at the bottom of this
    document for a complete list of values.
AddressResults : An array of AddressResults objects that shows the status of each
    address that failed. If no messages failed this array is empty.
TransactionReceipt : A string that can be sent to SocketLabs when debugging
    problem messages.
AddressResult :=
    EmailAddress : String
    Accepted : Boolean
    ErrorCode : String

EmailAddress : The recipient address which generated the warning or error.
Accepted : Whether or not the message was deliverable.
ErrorCode : The reason for message failure. See the appendix at the bottom of
    this document for a complete list of values.

Response Example (Successful):

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

Response Example (Error):

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

Back to top

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 code samples in a variety of development languages can be downloaded from github: http://github.com/socketlabs/

Back to top