API Reference (Inbound API)

SocketLabs On-Demand Inbound API Guide

Index

Inbound API Overview

API Purpose

The SocketLabs On-Demand Inbound API is part of SocketLabs’ Inbound service which parses inbound mail streams automatically generated JSON messages, which can be consumed by your own applications. This type of API is also commonly referred to as a “webhook” API. This API allows custom applications to easily process email messages and integrate their contents into a variety of applications such as support systems, discussion forums, and social media networks. More information about this feature can be found in the SocketLabs Knowledge BaseHow to configure Inbound Message Processing[▲]

Authentication & Access

To enable this feature, visit the “For Developers” dropdown menu in the SocketLabs On Demand Control Panel, select the “Configure Inbound API” page and enable the feature and to add the domain(s) to be processed with their MX records pointing to mx.socketlabs.com. Additionally, you will need to write and deploy an endpoint that can process the inbound mail streams. The URL of this endpoint is required by this feature’s configuration. This endpoint will need to both process and store inbound mail streams as they arrive, as well as respond to our service with the proper authentication information. All JSON messages sent from our services will contain the Secret Key seen on the control panel page as well as your server ID, which should be used to ensure that all notifications are coming from our services. All responses must contain the Validation Key, so that we continue to ensure that your endpoint is both identified and currently able to process notifications. We also ask that if the Secret Key does not match in a notification message, your application should return a 401 error response. [▲]

Security

Some of the values contained in the JSON messages may include data obtained from third-party mail servers and web browsers. SocketLabs will provide this data AS IS in the JSON messages, therefore it is important to treat this data as untrusted. If you are storing data from the JSON messages in your database, it is important to use prepared statements and/or parameterized queries in order to prevent potential injection attacks. Similarly, if you will be displaying this data to end users, it is important to make sure the data is encoded and/or escaped in order to avoid potential cross-site scripting or code execution. [▲]

Error Handling & Rate Limiting

Once your endpoint is configured properly, each Inbound message will count as one message towards your monthly message usage. If an endpoint is temporarily unavailable due to a system outage on our end, your end, or somewhere between — all message will be queued up for another delivery attempt in exactly the same way as email deferral works. Inbound API messages will be not be permanently failed and lost unless no contact can be made for at least four days.

In the case where your endpoint becomes unresponsive for long periods of time, we may disable the notification feature on your account to prevent generating large numbers of notifications which cannot be delivered. We would notify a user via email if this occurred, and the feature would need to be reconfigured via the control panel in order to be reactivated. [▲]

Release Notes

Version 1.1

Version 1.0

API Reference

Validation

This event is used for validating the endpoint that will receive POST events. It should be responded to with a message containing the Validation Key. [▲]

Event Format Type:

application/x-www-form-urlencoded

HTTP Method:

POST

ResponseParameters:

SecretKey
The secret key as defined in the Control Panel.
ServerId
The Server ID this event is associated with.
Type
Specifies the type of event. The value for this event is ‘Validation’.

Example:

PostBody:

  Type = Validation
  ServerId = 1000
  SecretKey = YOUR-SECRET-KEY

Inbound JSON Format

Every email message that passes through our Inbound Message Processing service is deconstructed into JSON and sent to the customer-defined endpoint via HTTP POST.  When handling this JSON structure, your applications should be able to handle additional undocumented key value pairs as we may add these in future versions of this API.

Event Format Type:

application/json

HTTP Method:

POST

Data Structure:

Each parsed email message is delivered using the following JSON structure:

{
    "SecretKey": "String",
    "ErrorLog": "String",
    "InboundIpAddress": "String",
    "InboundMailFrom": "String",
    "InboundRcptTo": "String",
    "SpamDetails": "String",
    "SpamScore" : "Double",
    "Message": {
        "To": [{
            "EmailAddress": "String",
            "FriendlyName": "String"
        }],
        "From": {
            "EmailAddress": "String",
            "FriendlyName": "String"
        },
        "Subject": "String",
        "TextBody": "String",
        "HtmlBody": "String",
        "MailingId": "String",
        "MessageId": "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"
            }]            
        }],
        "TextCharSet": "String",
        "HtmlCharSet": "String",
        "EmbeddedMedia": [{
            "Name": "String",
            "Content": "String",
            "ContentId": "String",
            "ContentType": "String",
            "CustomHeaders": [{
                "Name": "String",
                "Value": "String"
            }]
         "AdditionalBodyParts": [{ 
            "Name": "String", 
            "Content": "String", 
            "ContentId": "String", 
            "ContentType": "String", 
            "CustomHeaders": [{ 
                "Name": "String", 
                "Value": "String" 
           }]   
        }]
    }
}

The top-level JSON fields are:

ErrorLog
An explanation of why a message could not be parsed correctly if that message is malformed. Otherwise this entry is null.
InboundIpAddress
The IP address of the system that relayed the email message to the On-Demand server processing this message.
InboundMailFrom
The SMTP ‘MAIL FROM’ value used to send this message.
InboundRcptTo
The SMTP ‘RCPT TO’ value used to denote the recipient address.
Message
A single email message and all of its component parts.
SecretKey
A key provided by the On-Demand email API service when the Inbound feature is configured; the secret key is included in every Inbound message in order for the receiving endpoint to confirm that all JSON blobs it receives originated from the On-Demand network.
SpamDetails
The details behind the spam classification represented by a SpamScore.
SpamScore
The score assigned by SocketLabs’s spam scanning technology, indicating the likelihood that a message is spam.

The sub-fields within the Messages field 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.CustomHeaders
An array of header field data stored in Name/Value pairs
Message.EmbeddedMedia
An array of content blobs, specifically images, which are embedded into the message body.
Message.EmbeddedMedia.Content
The BASE64 encoded string containing the contents of an attachment.
Message.EmbeddedMedia.ContentId
When set, used to embed an image within the body of an email message.
Message.EmbeddedMedia.ContentType
The MIME type of an attachment.
Message.EmbeddedMedia.CustomHeaders
An array of header field data stored in Name/Value pairs.
Message.EmbeddedMedia.Name
The name of an attached file.
Message.AdditionalBodyParts
An array of content body blobs, that are not Text or HTML.  For example RTF, XML, Enriched, etc..
Message.AdditionalBodyParts.Content
The BASE64 encoded string containing the contents of an body part.
Message.AdditionalBodyParts.ContentId
If available, the content id taken from the bodypart header.
Message.AdditionalBodyParts.ContentType
The MIME type of an body part.  i.e. text/xml, text/enriched
Message.AdditionalBodyParts.CustomHeaders
An array of header field data stored in Name/Value pairs.
Message.AdditionalBodyParts.Name
If available, the name of the body part taken from the header.
Message.From
The EmailAddress/FriendlyName value pair for the sender of the message.
Message.HtmlBody
The HTML portion of the message body.
Message.HtmlCharSet
The character set used to encode the HtmlBody portion of the message.
Message.MailingId
SocketLabs header used to track batches of messages.
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.TextCharSet
The character set used to encode the TextBody portion of the message.
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 ‘[email protected]’.
*.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 such as ‘Content-Type’.
*.Value
The value of the header field such as ‘application/json’.

In the above descriptions, the use of *. means that the parameter can be found in many locations throughout the JSON, but the field represents the same information regardless of location. [▲]

Example JSON Message

This is an example of actual JSON from a parsed message.

{
    "SecretKey":"SOME SECRET KEY",
    "Message":{
        "TextCharSet":"us-ascii",
        "HtmlCharSet":"us-ascii",
        "EmbeddedMedia":null,
        "MailingId":null,
        "MessageId":null,
        "Subject":"This is the subject of a test message.",
        "TextBody":"This is the body of the test message.\r\n",
        "HtmlBody":"\u003chtml xmlns:v=\"urn:schemas-microsoft-com:vml\" xmlns:o=\"urn:schemas-microsoft-com:office:office\" xmlns:w=\"urn:schemas-microsoft-com:office:word\" xmlns:m=\"http://schemas.microsoft.com/office/2004/12/omml\" xmlns=\"http://www.w3.org/TR/REC-html40\"\u003e\u003chead\u003e\u003cMETA HTTP-EQUIV=\"Content-Type\" CONTENT=\"text/html; charset=us-ascii\"\u003e\u003cmeta name=Generator content=\"Microsoft Word 15 (filtered medium)\"\u003e\u003cstyle\u003e\u003c!--\r\n/* Font Definitions */\r\[email protected]\r\n\t{font-family:\"Cambria Math\";\r\n\tpanose-1:2 4 5 3 5 4 6 3 2 4;}\r\[email protected]\r\n\t{font-family:Calibri;\r\n\tpanose-1:2 15 5 2 2 2 4 3 2 4;}\r\n/* Style Definitions */\r\np.MsoNormal, li.MsoNormal, div.MsoNormal\r\n\t{margin:0in;\r\n\tmargin-bottom:.0001pt;\r\n\tfont-size:11.0pt;\r\n\tfont-family:\"Calibri\",\"sans-serif\";}\r\na:link, span.MsoHyperlink\r\n\t{mso-style-priority:99;\r\n\tcolor:#0563C1;\r\n\ttext-decoration:underline;}\r\na:visited, span.MsoHyperlinkFollowed\r\n\t{mso-style-priority:99;\r\n\tcolor:#954F72;\r\n\ttext-decoration:underline;}\r\nspan.EmailStyle17\r\n\t{mso-style-type:personal-compose;\r\n\tfont-family:\"Calibri\",\"sans-serif\";\r\n\tcolor:windowtext;}\r\n.MsoChpDefault\r\n\t{mso-style-type:export-only;\r\n\tfont-family:\"Calibri\",\"sans-serif\";}\r\[email protected] WordSection1\r\n\t{size:8.5in 11.0in;\r\n\tmargin:1.0in 1.0in 1.0in 1.0in;}\r\ndiv.WordSection1\r\n\t{page:WordSection1;}\r\n--\u003e\u003c/style\u003e\u003c!--[if gte mso 9]\u003e\u003cxml\u003e\r\n\u003co:shapedefaults v:ext=\"edit\" spidmax=\"1026\" /\u003e\r\n\u003c/xml\u003e\u003c![endif]--\u003e\u003c!--[if gte mso 9]\u003e\u003cxml\u003e\r\n\u003co:shapelayout v:ext=\"edit\"\u003e\r\n\u003co:idmap v:ext=\"edit\" data=\"1\" /\u003e\r\n\u003c/o:shapelayout\u003e\u003c/xml\u003e\u003c![endif]--\u003e\u003c/head\u003e\u003cbody lang=EN-US link=\"#0563C1\" vlink=\"#954F72\"\u003e\u003cdiv class=WordSection1\u003e\u003cp class=MsoNormal\u003eThis is the body of the test message.\u003co:p\u003e\u003c/o:p\u003e\u003c/p\u003e\u003c/div\u003e\u003c/body\u003e\u003c/html\u003e",
        "CustomHeaders":[
        {
            "Name":"Received",
            "Value":"from smtp176.dfw.emailsrvr.com ([67.192.241.176]) by mx.socketlabs.com with ESMTP; Mon, 20 May 2013 10:01:04 -0400"
        },
        {
            "Name":"Received",
            "Value":"from localhost (localhost.localdomain [127.0.0.1])by smtp7.relay.dfw1a.emailsrvr.com (SMTP Server) with ESMTP id F39D3258692for \[email protected]\u003e; Mon, 20 May 2013 10:00:47 -0400 (EDT)"
        },
        {
            "Name":"Received",
            "Value":"from smtp192.mex07a.mlsrvr.com (unknown [67.192.133.128])by smtp7.relay.dfw1a.emailsrvr.com (SMTP Server) with ESMTPS id 3E6022586DEfor \[email protected]\u003e; Mon, 20 May 2013 10:00:45 -0400 (EDT)"
        },
        {
            "Name":"Received",
            "Value":"from DFW1MBX19.mex07a.mlsrvr.com ([192.168.1.230]) byDFW1HUB14.mex07a.mlsrvr.com ([fe80::222:19ff:fe00:52bd%11]) with mapi; Mon,20 May 2013 09:00:45 -0500"
        },
        {
            "Name":"X-Virus-Scanned",
            "Value":"OK"
        },
        {
            "Name":"Date",
            "Value":"Mon, 20 May 2013 09:00:52 -0500"
        },
        {
            "Name":"Thread-Topic",
            "Value":"This is the subject of a test message."
        },
        {
            "Name":"Thread-Index",
            "Value":"Ac5VYnBo0JcanJnQTWSVA0k86Viq/Q=="
        },
        {
            "Name":"Message-ID",
            "Value":"\[email protected].mlsrvr.com\u003e"
        },
        {
            "Name":"Accept-Language",
            "Value":"en-US"
        },
        {
            "Name":"Content-Language",
            "Value":"en-US"
        },
        {
            "Name":"X-MS-Has-Attach",
            "Value":null
        },
        {
            "Name":"X-MS-TNEF-Correlator",
            "Value":null
        },
        {
            "Name":"acceptlanguage",
            "Value":"en-US"
        },
        {
            "Name":"Content-Type",
            "Value":"multipart/alternative;boundary=\"_000_CC49375B755FC1499ECDFBA782412D5F08F64FD3E6DFW1MBX19mex0_\""
        },
        {
            "Name":"MIME-Version",
            "Value":"1.0"
        }
        ],
        "To":[{
            "EmailAddress":"[email protected]",
            "FriendlyName":"Test Recipient"
        }],
        "Cc":null,
        "Bcc":null,
        "From":{
            "EmailAddress":"[email protected]",
            "FriendlyName":"Example Sender"
        },
        "ReplyTo":null,
        "Attachments":null
    },
    "InboundMailFrom":"[email protected]",
    "InboundRcptTo":"[email protected]",
    "InboundIpAddress":"10.10.10.10",
    "ErrorLog":null,
    "SpamScore":0,
    "SpamDetails":null
}

Please remember that, as seen above, many fields can be returned as null depending on the content of each message and its header, so endpoints need to be able to handle this in their processing. [▲]

Additional Resources

A sample Inbound API endpoint can be found in out public Github repository, located at: http://github.com/socketlabs/. [▲]

Customers Who Trust in SocketLabs

You’re in good company when working with SocketLabs. Here are some companies who have also trusted SocketLabs.

Why SocketLabs?

What Our Customers Are Saying!