ICOMMKT Transactional API API Reference

ICOMMKT Transactional API

API Endpoint

https://api.trx.icommarketing.com/

Request Content-Types: application/json, application/x-www-form-urlencoded

Response Content-Types: application/json

Schemes: https

Version: 1.0

Authentication

bearer_token

Authentication using bearer token

type

apiKey

name

Authorization

header

Email API

This endpoint is solely responsible for sending transactional emails with ICOMMKT through a specific server.

Email API

Send a single email

Request headers

Content-Type	required application/json
Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the API Tokens tab under your icomm server.

/email

Example request with curl

curl "https://api.trx.icommarketing.com/email" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d '{
  "From": "sender@example.com",
  "To": "receiver@example.com",
  "Subject": "Icomm test",
  "TextBody": "Hello dear icomm user.",
  "HtmlBody": "<html><body><strong>Hello</strong> dear icomm user.</body></html>",
  "MessageStream": "outbound"
}'

Body format

From	string	required The sender email address. Must have a registered and confirmed Sender Signature. To include a name, use the format "Full Name <sender@domain.com>" for the address.
To	string	required Recipient email address. Multiple addresses are comma separated. Max 50.
Cc	string	Cc recipient email address. Multiple addresses are comma separated. Max 50.
Bcc	string	Bcc recipient email address. Multiple addresses are comma separated. Max 50.
Subject	string	Email subject
Tag	string	Email tag that allows you to categorize outgoing emails and get detailed statistics.
HtmlBody	string	required If no `TextBody` specified HTML email message
TextBody	string	required If no `HtmlBody` specified Plain text email message
ReplyTo	string	Reply To override email address. Defaults to the Reply To set in the sender signature. Multiple addresses are comma separated.
Headers	array	List of custom headers to include.
TrackOpens	boolean	Activate open tracking for this email.
TrackLinks	string	Activate link tracking for links in the HTML or Text bodies of this email. Possible options: `None` `HtmlAndText` `HtmlOnly` `TextOnly`
Metadata	object	Custom metadata key/value pairs.
Attachments	array	List of attachments
MessageStream	string	Set message stream ID that's used for sending. If not provided, message will default to the "outbound" transactional stream.

Example body format

{
"From": "sender@example.com",
"To": "receiver@example.com",
"Cc": "copied@example.com",
"Bcc": "blind-copied@example.com",
"Subject": "Test",
"Tag": "Invitation",
"HtmlBody": "<b>Hello</b> <img src=\"cid:image.jpg\"/>",
"TextBody": "Hello",
"ReplyTo": "reply@example.com",
"Headers": [
{
"Name": "CUSTOM-HEADER",
"Value": "value"
}
],
"TrackOpens": true,
"TrackLinks": "None",
"Attachments": [
{
"Name": "readme.txt",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "text/plain"
},
{
"Name": "report.pdf",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "application/octet-stream"
},
{
"Name": "image.jpg",
"ContentID": "cid:image.jpg",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "image/jpeg"
}
],
"Metadata": {
"color":"blue",
"client-id":"12345"
},
"MessageStream": "outbound"
}

Email API

Send batch emails

Request headers

Content-Type	required application/json
Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

/email/batch

Example request with curl

curl "https://api.trx.icommarketing.com/email/batch" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d '[
  {
    "From": "sender@example.com",
    "To": "receiver1@example.com",
    "Subject": "Icomm test #1",
    "TextBody": "Hello dear icomm user.",
    "HtmlBody": "<html><body><strong>Hello</strong> dear icomm user.</body></html>",
    "MessageStream": "outbound"
  },
  {
    "From": "sender@example.com",
    "To": "receiver2@example.com",
    "Subject": "Icomm test #2",
    "TextBody": "Hello dear icomm user.",
    "HtmlBody": "<html><body><strong>Hello</strong> dear icomm user.</body></html>",
    "MessageStream": "outbound"
  }
]'

Body format

From	string	required The sender email address. Must have a registered and confirmed Sender Signature. To include a name, use the format "Full Name <sender@domain.com>" for the address.
To	string	required Recipient email address. Multiple addresses are comma separated. Max 50.
Cc	string	Cc recipient email address. Multiple addresses are comma separated. Max 50.
Bcc	string	Bcc recipient email address. Multiple addresses are comma separated. Max 50.
Subject	string	Email subject
Tag	string	Email tag that allows you to categorize outgoing emails and get detailed statistics.
HtmlBody	string	If no `TextBody` specified HTML email message
TextBody	string	If no `HtmlBody` specified Plain text email message
ReplyTo	string	Reply To override email address. Defaults to the Reply To set in the sender signature.
Headers	array	List of custom headers to include.
TrackOpens	boolean	Activate open tracking for this email.
TrackLinks	string	Activate link tracking for links in the HTML or Text bodies of this email. Possible options: `None` `HtmlAndText` `HtmlOnly` `TextOnly`
Metadata	object	Custom metadata key/value pairs.
Attachments	array	List of attachments
MessageStream	string	Set message stream ID that's used for sending. If not provided, message will default to the "outbound" transactional stream.

Example body format

[
{
"From": "sender@example.com",
"To": "receiver1@example.com",
"Cc": "copied@example.com",
"Bcc": "blank-copied@example.com",
"Subject": "Test",
"Tag": "Invitation",
"HtmlBody": "<b>Hello</b> <img src=\"cid:image.jpg\"/>",
"TextBody": "Hello",
"ReplyTo": "reply@example.com",
"Headers": [
{
"Name": "CUSTOM-HEADER",
"Value": "value"
}
],
"TrackOpens": true,
"TrackLinks": "None",
"Attachments": [
{
"Name": "readme.txt",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "text/plain"
},
{
"Name": "report.pdf",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "application/octet-stream"
},
{
"Name": "image.jpg",
"ContentID": "cid:image.jpg",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "image/jpeg"
}
],
"Metadata": {
"color":"green",
"client-id":"12345"
},
"MessageStream": "outbound"
},
{
"From": "sender@example.com",
"To": "receiver2@example.com",
"Cc": "copied@example.com",
"Bcc": "blank-copied@example.com",
"Subject": "Test",
"Tag": "Invitation",
"HtmlBody": "<b>Hello</b> <img src=\"cid:image.jpg\"/>",
"TextBody": "Hello",
"ReplyTo": "reply@example.com",
"Headers": [
{
"Name": "CUSTOM-HEADER",
"Value": "value"
}
],
"TrackOpens": true,
"TrackLinks": "None",
"Attachments": [
{
"Name": "readme.txt",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "text/plain"
},
{
"Name": "report.pdf",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "application/octet-stream"
},
{
"Name": "image.jpg",
"ContentID": "cid:image.jpg",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "image/jpeg"
}
],
"Metadata": {
"color":"blue",
"client-id":"54321"
},
"MessageStream": "outbound"
}
]

Bounces API

Lets you access all reports regarding your bounces for a specific server.

Bounces API

Get delivery Status

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/deliverystats

Example request with curl

curl "https://api.trx.icommarketing.com/deliverystats" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Response

InactiveMails	integer	Number of inactive emails
Bounces	array	List of bounce types with total counts.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"InactiveMails": 192,
"Bounces": [
{
"Name": "All",
"Count": 253
},
{
"Type": "HardBounce",
"Name": "Hard bounce",
"Count": 195
},
{
"Type": "Transient",
"Name": "Message delayed",
"Count": 10
},
{
"Type": "AutoResponder",
"Name": "Auto responder",
"Count": 14
},
{
"Type": "SpamNotification",
"Name": "Spam notification",
"Count": 3
},
{
"Type": "SoftBounce",
"Name": "Soft bounce",
"Count": 30
},
{
"Type": "SpamComplaint",
"Name": "Spam complaint",
"Count": 1
}
]
}

Bounces API

Get bounces

The bounces search allows you to return up-to 10,000 bounces in a search. For searches where you're looking to retrieve more than 10,000 bounces use parameters like todate and fromdate to filter the messages.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/bounces

Example request with curl

curl "https://api.trx.icommarketing.com/bounces?type=HardBounce&inactive=true&count=50&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

count	required Number of bounces to return per request. Max 500. Count + Offset cannot exceed 10,000 bounces.
offset	required Number of bounces to skip. Count + Offset cannot exceed 10,000 bounces.
type	Filter by type of bounce
inactive	Filter by emails that were deactivated by icomm due to the bounce. Set to `true` or `false`. If this isn’t specified it will return both active and inactive.
emailFilter	Filter by email address
tag	Filter by tag
messageID	Filter by messageID
fromdate	Filter messages starting from the date/time specified (inclusive). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.
todate	Filter messages up to the date/time specified (inclusive). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.
messagestream	Filter by message stream ID. If not provided, message will default to the `outbound` transactional stream.

Response

TotalCount	integer	Number of records returned
Bounces	array	List of individual bounces
ID	integer	ID of bounce
Type	string	Bounce type
TypeCode	integer	Bounce type code
Name	string	Bounce type name
Tag	string	Tag name
MessageID	string	ID of message
ServerID	string	ID of server that sent the message
MessageStream	string	The outbound sending message stream for the message.
Description	string	Description of bounce
Details	string	Details on the bounce
Email	string	Email address that bounced
From	string	Original sender of the bounced message, if available. For example, spam complaints do not include the original sender address.
BouncedAt	string	Timestamp of bounce
DumpAvailable	boolean	Specifies whether or not you can get a raw dump from this bounce. icomm doesn’t store bounce dumps older than 30 days.
Inactive	boolean	Specifies if the bounce caused icomm to deactivate this email.
CanActivate	boolean	Specifies whether or not you are able to reactivate this email.
Subject	string	Email subject
Content	string	Bounce content

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"TotalCount": 253,
"Bounces": [
{
"ID": 692560173,
"Type": "HardBounce",
"TypeCode": 1,
"Name": "Hard bounce",
"Tag": "Invitation",
"MessageID": "2c1b63fe-43f2-4db5-91b0-8bdfa44a9316",
"ServerID": 23,
"MessageStream": "outbound",
"Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
"Details": "action: failed\r\n",
"Email": "anything@blackhole.icommapp.com",
"From": "sender@icommapp.com",
"BouncedAt": "2014-01-15T16:09:19.6421112-05:00",
"DumpAvailable": false,
"Inactive": false,
"CanActivate": true,
"Subject": "SC API5 Test"
},
{
"ID": 676862817,
"Type": "HardBounce",
"TypeCode": 1,
"Name": "Hard bounce",
"Tag": "Invitation",
"MessageID": "623b2e90-82d0-4050-ae9e-2c3a734ba091",
"ServerID": 23,
"MessageStream": "outbound",
"Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
"Details": "smtp;554 delivery error: dd This user doesn't have a yahoo.com account (vicelcown@yahoo.com) [0] - mta1543.mail.ne1.yahoo.com",
"Email": "vicelcown@yahoo.com",
"From": "sender@icommapp.com",
"BouncedAt": "2013-10-18T09:49:59.8253577-04:00",
"DumpAvailable": false,
"Inactive": true,
"CanActivate": true,
"Subject": "Production API Test"
}
]
}

Bounces API

Get a single bounce

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/bounces/{bounceid}

Example request with curl

curl "https://api.trx.icommarketing.com/bounces/{bounceid}" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Response

ID	integer	ID of bounce
Type	string	Bounce type
TypeCode	integer	Bounce type code
Name	string	Bounce type name
Tag	string	Tag name
MessageID	string	ID of message
ServerID	string	ID of server that sent the message
MessageStream	string	The outbound sending message stream for the message.
Description	string	Description of bounce
Details	string	Details on the bounce
Email	string	Email address that bounced
From	string	Original sender of the bounced message, if available. For example, spam complaints do not include the original sender address.
BouncedAt	string	Timestamp of bounce
DumpAvailable	boolean	Specifies whether or not you can get a raw dump from this bounce. icomm doesn’t store bounce dumps older than 30 days.
Inactive	boolean	Specifies if the bounce caused icomm to deactivate this email.
CanActivate	boolean	Specifies whether or not you are able to reactivate this email.
Subject	string	Email subject
Content	string	Bounce content

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"ID": 692560173,
"Type": "HardBounce",
"TypeCode": 1,
"Name": "Hard bounce",
"Tag": "Invitation",
"MessageID": "2c1b63fe-43f2-4db5-91b0-8bdfa44a9316",
"ServerID": 23,
"MessageStream": "outbound",
"Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
"Details": "action: failed\r\n",
"Email": "anything@blackhole.icommapp.com",
"From": "sender@icommapp.com",
"BouncedAt": "2014-01-15T16:09:19.6421112-05:00",
"DumpAvailable": false,
"Inactive": false,
"CanActivate": true,
"Subject": "SC API5 Test",
"Content": "Return-Path: <>\r\nReceived: …"
}

Bounces API

Get bounce dump

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/bounces/{bounceid}/dump

Example request with curl

curl "https://api.trx.icommarketing.com/bounces/{bounceid}/dump" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Response

Body	string	Raw source of bounce. If no dump is available this will return an empty string.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Body": "SMTP dump data"
}

Bounces API

Activate a bounce

Request headers

Content-Type	required application/json
Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

PUT

/bounces/{bounceid}/activate

Example request with curl

curl "https://api.trx.icommarketing.com/bounces/{bounceid}/activate" \
  -X PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d ""

Response

Message	string	Response message
Bounce	object	Bounce details
ID	integer	ID of bounce
Type	string	Bounce type
TypeCode	integer	Bounce type code
Name	string	Bounce type name
Tag	string	Tag name
MessageID	string	ID of message
ServerID	string	ID of server that sent the message
MessageStream	string	The outbound sending message stream for the message.
Description	string	Description of bounce
Details	string	Details on the bounce
Email	string	Email address that bounced
From	string	Original sender of the bounced message, if available. For example, spam complaints do not include the original sender address.
BouncedAt	string	Timestamp of bounce
DumpAvailable	boolean	Specifies whether or not you can get a raw dump from this bounce. Icomm doesn’t store bounce dumps older than 30 days.
Inactive	boolean	Specifies if the bounce caused icomm to deactivate this email.
CanActivate	boolean	Specifies whether or not you are able to reactivate this email.
Subject	string	Email subject
Content	string	Bounce content

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Message": "OK",
"Bounce": {
"ID": 692560173,
"Type": "HardBounce",
"TypeCode": 1,
"Name": "Hard bounce",
"Tag": "Invitation",
"MessageID": "2c1b63fe-43f2-4db5-91b0-8bdfa44a9316",
"ServerID": 23,
"MessageStream": "outbound",
"Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
"Details": "action: failed\r\n",
"Email": "anything@blackhole.icommapp.com",
"From": "sender@icommapp.com",
"BouncedAt": "2014-01-15T16:09:19.6421112-05:00",
"DumpAvailable": false,
"Inactive": false,
"CanActivate": true,
"Subject": "SC API5 Test",
"Content": "Return-Path: <>\r\nReceived: …"
}
}

Bounces API

Get an array of tags that have generated bounces for a given server.

GET /bounces/tags

The /bounces/tags endpoint is used to return all tags from bounced messages as a string array. This endpoint gets extremely low utilization, so we are deprecating it on December 2nd, 2019.

Templates API

Lets you manage templates for a specific server. Please note that a Server may have up to 300 active templates. Requests that exceed this limit won't be processed.

Templates API

List templates

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/templates

Example request with curl

curl "https://api.trx.icommarketing.com/templates?count=100&offset=0&LayoutTemplate=my-layout" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

Count	required The number of templates to return.
Offset	required The number of templates to "skip" before returning results.
TemplateType	Filters templates based on template type (layout template or standard template). Possible options: `All` `Standard` `Layout`. Defaults to `All`.
LayoutTemplate	Filter results by layout alias.

Response

TotalCount	integer	The total number of templates associated with the current server.
Templates	array	A list of templates associated with this server.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"TotalCount": 2,
"Templates": [
{
"Active": true,
"TemplateId": 1234,
"Name": "Password Recovery Email",
"Alias": "password-recovery",
"TemplateType": "Standard",
"LayoutTemplate": "my-layout"
},
{
"Active": true,
"TemplateId": 5678,
"Name": "Default Layout",
"Alias": "my-layout",
"TemplateType": "Layout",
"LayoutTemplate": null
}]
}

Templates API

Create a template

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

/templates

Example request with curl

curl "https://api.trx.icommarketing.com/templates" \
  -X POST \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d '{
          "Name": "Welcome Email",
          "Alias": "onboarding-v1",
          "HtmlBody": "<html><body>Hello{{name}}<body><html>",
          "TextBody": "Hello, {{name}}",
          "Subject": "Hello, from {{company.name}}",
          "TemplateType": "Standard",
          "LayoutTemplate": "my-layout"
      }'

Body format

Name	string	required Name of template
Alias	string	An optional string you can provide to identify this template (if creating a standard template). Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter.
HtmlBody	string	required The content to use for the HtmlBody when this template is used to send email. Required if `TextBody` is not specified. A content placeholder is required to be present for a layout template, and can be placed only once in the HtmlBody.
TextBody	string	required The content to use for the TextBody when this template is used to send email. Required if `HtmlBody` is not specified. A content placeholder is required to be present for a layout template, and can be placed only once in the TextBody.
Subject	string	required The content to use for the Subject when this template is used to send email. Subject is only required on standard templates. Subjects are not allowed for layout templates and will result in an API error.
TemplateType	string	Available when creating a template. To set if a template is standard template or layout template. Possible options: `Standard` or `Layout`. Defaults to `Standard`. After creation, it's not possible to change a template type.
LayoutTemplate	string	An optional string to specify which Layout Template to use (via layout alias) for an existing Layout Template when creating a standard template. Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter. The API will throw an error if `LayoutTemplate` is present and the template type is a Layout. This field can also be set to null by using an empty string "".

Example response

{
"Name": "Onboarding Email",
"Subject": "Hello from {{company.name}}!",
"TextBody": "Hello, {{name}}!",
"HtmlBody": "<html><body>Hello, {{name}}!</body></html>",
"TemplateType": "Standard",
"Alias": "onboarding-v1",
"LayoutTemplate": "my-layout"
}

Templates API

Get a template

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/templates/{templateIdOrAlias}

Example request with curl

curl "https://api.trx.icommarketing.com/templates/{templateIdOrAlias}" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Response

TemplateId	integer	ID of template
Name	string	Name of template
Subject	string	The content to use for the Subject when this template is used to send email.
HtmlBody	string	The content to use for the HtmlBody when this template is used to send email.
TextBody	string	The content to use for the TextBody when this template is used to send email.
AssociatedServerId	integer	The ID of the Server with which this template is associated.
Active	boolean	Indicates that this template may be used for sending email.
Alias	string	An optional string you can provide to identify this Template. Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter.
TemplateType	string	The type of template returned. Possible options: `Standard` or `Layout`.
LayoutTemplate	string	If returned template is a standard template and uses a layout template, this returns the layout template alias. `null` if no layout.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Name": "Onboarding Email",
"TemplateId": 1234,
"Subject": "Hi there, {{Name}}",
"HtmlBody": "Hello dear icomm user. {{Name}}",
"TextBody": "{{Name}} is a {{Occupation}}",
"AssociatedServerId": 1,
"Active": false,
"Alias": "onboarding-v1",
"TemplateType": "Standard",
"LayoutTemplate": "my-layout"
},
{
"Name": "Receipt Email",
"TemplateId": 1235,
"Subject": "Receipt for {{ product_name }}",
"HtmlBody": "<body><span class="preheader">This is a receipt for {{ product_name }}...",
"TextBody": "This is a receipt for {{ product_name }}",
"AssociatedServerId": 1,
"Active": false,
"Alias": "receipt-v1",
"TemplateType": "Standard",
"LayoutTemplate": "null"
}

Templates API

Edit a template

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

put

/templates/{templateIdOrAlias}

Example request with curl

curl "https://api.trx.icommarketing.com/templates/{templateIdOrAlias}" \
  -X PUT \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d '{
          "Name": "Onboarding Email",
          "Subject": "Hello from {{company.name}}!",
          "TextBody": "Hello, {{name}}!",
          "HtmlBody": "<html><body>Hello, {{name}}!</body></html>",
          "Alias": "welcome-v1"
      }'

Body format

Name	string	required Name of template
Subject	string	required The content to use for the Subject when this template is used to send email.
HtmlBody	string	required The content to use for the HtmlBody when this template is used to send email. Required if `TextBody` is not specified.
TextBody	string	required The content to use for the TextBody when this template is used to send email. Required if `HtmlBody` is not specified.
Alias	string	An optional string you can provide to identify this Template. Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter.
LayoutTemplate	string	An optional string to specify which Layout Template to use (via layout alias) for an existing Layout Template when creating a standard template. Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter. The API will throw an error if LayoutTemplate is present and the template type is a Layout. This field can also be set to null by using an empty string "".

Example body format

{
"Name": "Onboarding Email",
"Subject": "Hello from {{company.name}}!",
"TextBody": "Hello, {{name}}!",
"HtmlBody": "<html><body>Hello, {{name}}!</body></html>",
"Alias": "welcome-v1",
"LayoutTemplate": "my-layout"
}

Templates API

Delete a template

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

delete

/templates/{templateIdOrAlias}

Example request with curl

curl "https://api.trx.icommarketing.com/templates/{templateIdOrAlias}" \
  -X DELETE \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Response

ErrorCode	integer	API Error Codes
Message	string	Associated success or error message.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"ErrorCode": 0,
"Message": "Template 1234 removed."
}

Templates API

Validate a template

Request headers

Accept	required application/json
X-Trx-Api-Key	This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

/templates/validate

Example request with curl

curl "https://api.trx.icommarketing.com/templates/validate" \
  -X POST \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d '{
          "Subject": "{{#company}}{{name}}{{/company}} {{subjectHeadline}}",
          "HtmlBody": "{{#company}}{{address}}{{/company}}{{#each person}} {{name}} {{/each}}",
          "TextBody": "{{#company}}{{phone}}{{/company}}{{#each person}} {{name}} {{/each}}",
          "TestRenderModel": {
            "userName": "bobby joe"
          },
         "TemplateType": "Standard",
         "LayoutTemplate": "my-layout"
      }'

Body format

Subject	string	required The subject content to validate. Must be specified if `HtmlBody` or `TextBody` are not.
HtmlBody	string	required The HTML body content to validate. Must be specified if `TextBody` or `Subject` are not. A content placeholder is required to be present to validate a layout template, and can be placed only once in the HtmlBody.
TextBody	string	required The plain text body content to validate. Must be specified if `Subject` or `HtmlBody` are not. A content placeholder is required to be present to validate a layout template, and can be placed only once in the TextBody.
TestRenderModel	object	The template model to be used when rendering test content.
InlineCssForHtmlTestRender	boolean	When `HtmlBody` is specified, the test render will have `style` blocks inlined as style attributes on matching html elements. You may disable the css inlining behavior by passing `false` for this parameter.
TemplateType	string	Validates templates based on template type (layout template or standard template). Possible options: `Standard` or `Layout`. Defaults to `Standard`.
LayoutTemplate	string	An optional string to specify which layout template alias to use to validate a standard template. If not provided a standard template will not use a layout template.

Example body format

{
"Subject": "{{#company}}{{name}}{{/company}} {{subjectHeadline}}",
"HtmlBody": "{{#company}}{{address}}{{/company}}{{#each person}} {{name}} {{/each}}",
"TextBody": "{{#company}}{{phone}}{{/company}}{{#each person}} {{name}} {{/each}}",
"TestRenderModel": {
"userName": "bobby joe"
},
"TemplateType": "Standard",
"LayoutTemplate": "my-layout"
}

Templates API

Send email with template

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the API Tokens tab under your icomm server.

/email/withTemplate/

Example request with curl

curl "https://api.trx.icommarketing.com/email/withTemplate" \
  -X POST \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d '{
          "From": "sender@example.com",
          "To": "receiver@example.com",
          "TemplateId": 1234,
          "TemplateModel": {
              "user_name": "John Smith"
          }
      }'

Body format

TemplateId	integer	required The template to use when sending this message. Required if `TemplateAlias` is not specified.
TemplateAlias	string	required The alias of a template to use when sending this message. Required if `TemplateId` is not specified.
TemplateModel	object	required The model to be applied to the specified template to generate `HtmlBody`, `TextBody`, and `Subject`.
InlineCss	boolean	By default, if the specified template contains an `HTMLBody`, we will apply the style blocks as inline attributes to the rendered HTML content. You may opt-out of this behavior by passing `false` for this request field.
From	string	required The sender email address. Must have a registered and confirmed Sender Signature. To include a name, use the format "Full Name <sender@domain.com>" for the address.
To	string	required Recipient email address. Multiple addresses are comma separated. Max 50.
Cc	string	Cc recipient email address. Multiple addresses are comma separated. Max 50.
Bcc	string	Bcc recipient email address. Multiple addresses are comma separated. Max 50.
Tag	string	Email tag that allows you to categorize outgoing emails and get detailed statistics.
ReplyTo	string	Reply To override email address. Defaults to the Reply To set in the sender signature.
Headers	array	List of custom headers to include.
TrackOpens	boolean	Activate open tracking for this email.
TrackLinks	string	Activate link tracking for links in the HTML or Text bodies of this email. Possible options: `None` `HtmlAndText` `HtmlOnly` `TextOnly`
Attachments	array	List of attachments
Metadata	object	Custom metadata key/value pairs.
MessageStream	string	Set message stream ID that's used for sending. If not provided, message will default to the `outbound` transactional stream.

Example body format

{
"TemplateId": 1234,
"TemplateModel": {
"user_name": "John Smith",
"company": {
"name": "ACME"
}
},
"InlineCss": true,
"From": "sender@example.com",
"To": "receiver@example.com",
"Cc": "copied@example.com",
"Bcc": "blank-copied@example.com",
"Tag": "Invitation",
"ReplyTo": "reply@example.com",
"Headers": [
{
"Name": "CUSTOM-HEADER",
"Value": "value"
}
],
"TrackOpens": true,
"TrackLinks": "None",
"Attachments": [
{
"Name": "readme.txt",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "text/plain"
},
{
"Name": "report.pdf",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "application/octet-stream"
}
],
"Metadata": {
"color":"blue",
"client-id":"12345"
},
"MessageStream": "outbound"
}

Templates API

Send batch with templates

Request headers

Content-Type	required application/json
Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

/email/batchWithTemplates

Example request with curl

curl "https://api.trx.icommarketing.com/email/batchWithTemplates" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d '{
    "Messages": [
        {
            "From": "sender@example.com",
            "To": "receiver1@example.com",
            "TemplateId": 12345,
            "TemplateModel": {
                "fizz": "buzz"
            }
        },
        {
            "From": "sender@example.com",
            "To": "receiver2@example.com",
            "TemplateAlias": "welcome-notification",
            "TemplateModel": {
                "fizz": "buzz"
            }
        }
    ]
}'

Body format

Messages	array	required The list of templates to send. Please note that we accept up to 500 messages per API call.
TemplateAlias	string	The template to use for this message. This value is required if TemplateId is not supplied. If both are supplied, TemplateId will be used to select the template.
TemplateId	integer	The template to use for this message. This value is required if TemplateAlias is not supplied. If both are supplied, TemplateId will be used to select the template.
From	string	required The sender email address. Must have a registered and confirmed Sender Signature. To include a name, use the format "Full Name <sender@domain.com>" for the address.
To	string	required Recipient email address. Multiple addresses are comma separated. Max 50.
Cc	string	Cc recipient email address. Multiple addresses are comma separated. Max 50.
Bcc	string	Bcc recipient email address. Multiple addresses are comma separated. Max 50.
Tag	string	Email tag that allows you to categorize outgoing emails and get detailed statistics.
ReplyTo	string	Reply To override email address. Defaults to the Reply To set in the sender signature.
Headers	array	List of custom headers to include.
TrackOpens	boolean	Activate open tracking for this email.
TrackLinks	string	Activate link tracking for links in the HTML or Text bodies of this email. Possible options: `None` `HtmlAndText` `HtmlOnly` `TextOnly`
Attachments	array	List of attachments
Metadata	object	Custom metadata key/value pairs.
MessageStream	string	Set message stream ID that's used for sending. If not provided, message will default to the `outbound` transactional stream.

Example body format

{
"Messages": [
{
"From": "sender@example.com",
"To": "receiver@example.com",
"Cc": "copied@example.com",
"Bcc": "blank-copied@example.com",
"Tag": "Invitation",
"ReplyTo": "reply@example.com",
"TemplateAlias": "invitation-letter",
"TemplateModel": {
"fizz": "buzz"
},
"Headers": [
{
"Name": "CUSTOM-HEADER",
"Value": "value"
}
],
"TrackOpens": true,
"TrackLinks": "None",
"Attachments": [
{
"Name": "readme.txt",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "text/plain"
},
{
"Name": "report.pdf",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "application/octet-stream"
},
{
"Name": "image.jpg",
"ContentID": "cid:image.jpg",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "image/jpeg"
}
],
"Metadata": {
"color":"blue",
"client-id":"12345"
},
"MessageStream": "outbound"
}
]
}

Messages API

Lets you get all the details about any outbound or inbound message that you sent or received through a specific server. Messages expire after 45 days.

Messages API

Outbound message search

The message search allows you to return up-to 10,000 messages in a search. For searches where you're looking to retrieve more than 10,000 messages use parameters like todate and fromdate to filter the messages.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/messages/outbound

Example request with curl

curl "https://api.trx.icommarketing.com/messages/outbound?recipient=john.doe@yahoo.com&count=50&offset=0&tag=welcome&status=sent&todate=2015-01-12&fromdate=2015-01-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

count	required Number of messages to return per request. Max 500. Count + Offset cannot exceed 10,000 messages.
offset	required Number of messages to skip. Count + Offset cannot exceed 10,000 messages.
recipient	Filter by the user who was receiving the email.
fromemail	Filter by the sender email address.
tag	Filter by tag
status	Filter by status (`queued` or `sent` / `processed`). Note that `sent` and `processed` will return the same results and can be used interchangeably.
todate	Filter messages up to the date/time specified (inclusive). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.
fromdate	Filter messages starting from the date/time specified (inclusive). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.
subject	Filter by email subject.
messagestream	Filter by message stream ID. If not provided, message will default to the 'outbound' transactional stream.
metadata_	Filter by metadata value. e.g. metadata_color. You can currently only search by a single metadata field at a time.

Response

TotalCount	integer	Indicates the number of messages that matched the search criteria you specified. An email that is sent to multiple recipients is counted as 1 message in the Messages API, so `TotalCount` will be less than the total number of emails sent if some messages were sent to multiple recipients. On the Statistics page in the icomm UI, a message sent to multiple recipients is counted once for each recipient, so the `Sent` number on the Statistics page indicates the total number of emails sent. This ensures accurate tracking of opens, link clicks, etc.
Messages	array	List of objects that each represent a single message.

Example body format

HTTP/1.1 200 OK
Content-Type: application/json

{
"TotalCount": 194,
"Messages": [
{
"Tag": "Invitation",
"MessageID": "0ac29aee-e1cd-480d-b08d-4f48548ff48d",
"MessageStream": "outbound",
"To": [
{
"Email": "john.doe@yahoo.com",
"Name": null
}
],
"Cc": [],
"Bcc": [],
"Recipients": [
"john.doe@yahoo.com"
],
"ReceivedAt": "2014-02-20T07:25:02.8782715-05:00",
"From": "\"Joe\" <joe@domain.com>",
"Subject": "staging",
"Attachments": [],
"Status": "Sent",
"TrackOpens" : true,
"TrackLinks" : "HtmlAndText",
"Metadata": {
"color": "blue",
"client-id": "12345"
},
"Sandboxed": false
}
]
}

Messages API

Outbound message details

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/messages/outbound/{messageid}/details

Example request with curl

curl "https://api.trx.icommarketing.com/messages/outbound/{messageid}/details" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Response

TextBody	string	Text body of the message.
HtmlBody	string	Html body of the message.
Body	string	Raw source of the message.
Tag	string	Tags associated with this message.
MessageID	string	Unique ID of the message.
MessageStream	string	The outbound sending message stream for the message.
To	string	List of objects that contain To recipients.
Cc	string	List of objects that contain Cc recipients.
Bcc	string	List of objects that contain Bcc recipients.
Recipients	string	List of recipients.
ReceivedAt	string	Timestamp of when the message was sent by icomm. Corresponds with the Processed event in the UI.
From	string	The sender email address.
Subject	string	Email subject
Attachments	array	List of objects that each represent an attachment.
Status	string	Status of message in your icomm Activity. Possible statuses: `Sent`, `Processed`, or `Queued`.
TrackOpens	boolean	Indicates whether Open Tracking was enabled for this message.
TrackLinks	string	Indicates whether Link Tracking was enabled for this message. Possible options: `None` `HtmlAndText` `HtmlOnly` `TextOnly`
Metadata	array	Key/Value metadata pairs. You can currently only search by a single metadata field at a time.
Sandboxed	boolean	Indicates whether the message was sandboxed or not. This is determined based on the Server type
MessageEvents	array	List of summaries (MessageEvent) of things that have happened to this message. They can be `SubscriptionChanged`, `Delivered`, `Transient`, `Opened`, `LinkClicked`, or `Bounced` as shown in the type field.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"TextBody": "Thank you for your order...",
"HtmlBody": "<p>Thank you for your order...</p>",
"Body": "SMTP dump data",
"Tag": "product-orders",
"MessageID": "07311c54-0687-4ab9-b034-b54b5bad88ba",
"MessageStream": "outbound",
"To": [
{
"Email": "john.doe@yahoo.com",
"Name": null
}
],
"Cc": [],
"Bcc": [],
"Recipients": [
"john.doe@yahoo.com"
],
"ReceivedAt": "2014-02-14T11:12:54.8054242-05:00",
"From": "\"Joe\" <joe@domain.com>",
"Subject": "Parts Order #5454",
"Attachments": [
"myimage.png",
"mypaper.doc"
],
"Status": "Sent",
"TrackOpens" : true,
"TrackLinks" : "HtmlOnly",
"Metadata": {
"color": "blue",
"client-id": "12345"
},
"Sandboxed": false,
"MessageEvents": [
{
"Recipient": "john.doe@yahoo.com",
"Type": "Delivered",
"ReceivedAt": "2014-02-14T11:13:10.8054242-05:00",
"Details": {
"DeliveryMessage": "smtp;250 2.0.0 OK l10si21599969igu.63 - gsmtp",
"DestinationServer": "yahoo-smtp-in.l.yahoo.com (433.899.888.26)",
"DestinationIP": "173.194.74.256"
}
},
{
"Recipient": "john.doe@yahoo.com",
"Type": "Transient",
"ReceivedAt": "2014-02-14T11:12:10.8054242-05:00",
"Details": {
"DeliveryMessage": "smtp;400 Server cannot accept messages at this time, please try again later",
"DestinationServer": "yahoo-smtp-in.l.yahoo.com (433.899.888.26)",
"DestinationIP": "173.194.74.256"
}
},
{
"Recipient": "john.doe@yahoo.com",
"Type": "Opened",
"ReceivedAt": "2014-02-14T11:20:10.8054242-05:00",
"Details": {
"Summary": "Email opened with Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)"
}
},
{
"Recipient": "badrecipient@example.com",
"Type": "Bounced",
"ReceivedAt": "2014-02-14T11:20:15.8054242-05:00",
"Details": {
"Summary": "smtp;550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces.",
"BounceID": "374814878"
}
},
{
"Recipient": "badrecipient@example.com",
"Type": "SubscriptionChanged",
"ReceivedAt": "2014-02-14T11:21:15.8054242-05:00",
"Details": {
"Origin": "Recipient",
"SuppressSending": "True"
}
},
{
"Recipient":"click-tracked@example.com",
"Type":"LinkClicked",
"ReceivedAt":"2016-10-05T16:03:56.0000000-04:00",
"Details":{
"Summary":"Tracked Link 'https://example.com/a/path/to/the/future?queryValue=1&queryValue=2' was clicked from the HTMLBody.",
"Link":"https://example.com/a/path/to/the/future?queryValue=1&queryValue=2",
"ClickLocation":"HTML"
}
}
]
}

Messages API

Outbound message dump

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/messages/outbound/{messageid}/dump

Example request with curl

curl "https://api.trx.icommarketing.com/messages/outbound/{messageid}/dump" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Response

Body	string	Raw source of message. If no dump is available this will return an empty string.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Body": "From: \"John Doe\" <john.doe@yahoo.com> \r\nTo: \"john.doe@yahoo.com\" <john.doe@yahoo.com>\r\nReply-To: joe@domain.com\r\nDate: Fri, 14 Feb 2014 11:12:56 -0500\r\nSubject: Parts Order #5454\r\nMIME-Version: 1.0\r\nContent-Type: text/plain; charset=UTF-8\r\nContent-Transfer-Encoding: quoted-printable\r\nX-Mailer: aspNetEmail ver 4.0.0.22\r\nX-Job: 44013_34141\r\nX-virtual-MTA: shared1\r\nX-Complaints-To: abuse@icommapp.com\r\nX-PM-RCPT: |bTB8NDQwMTN8MzQxNDF8anBAd2lsZGJpdC5jb20=|\r\nX-PM-Tag: product-orders\r\nX-PM-Message-Id: 07311c54-0687-4ab9-b034-b54b5bad88ba\r\nMessage-ID: <SC-ORD-MAIL4390fbe08b95f4257984dcaed896b4730@SC-ORD-MAIL4>\r\n\r\nThank you for your order=2E=2E=2E\r\n"
}

Messages API

Inbound message search

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/messages/inbound

Example request with curl

curl "https://api.trx.icommarketing.com/messages/inbound?recipient=john.doe@yahoo.com&count=50&offset=0&fromdate=2015-02-01&todate=2015-03-01&status=blocked" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

count	required Number of messages to return per request. Max 500. Count + Offset cannot exceed 10,000 messages.
offset	required Number of messages to skip. Count + Offset cannot exceed 10,000 messages.
recipient	Filter by the user who was receiving the email.
fromemail	Filter by the sender email address.
tag	Filter by tag
subject	Filter by email subject
mailboxhash	Filter by mailboxhash
status	Filter by status (`blocked`, `processed` , `queued`, `failed`, `scheduled`)
todate	Filter messages up to the date specified (inclusive). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.
fromdate	Filter messages starting from the date specified (inclusive). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.

Response

TotalCount	integer	Indicates the number of messages that matched the search criteria you specified. An email that is sent to multiple recipients is counted as 1 message in the Messages API, so `TotalCount` will be less than the total number of emails sent if some messages were sent to multiple recipients. On the Statistics page in the icomm UI, a message sent to multiple recipients is counted once for each recipient, so the `Sent` number on the Statistics page indicates the total number of emails sent. This ensures accurate tracking of opens, link clicks, etc.
Messages	array	List of objects that each represent a single message.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"TotalCount": 7,
"InboundMessages": [
{
"From": "dart-zzzzz@yandex.ru",
"FromName": "Dart Zzzzz",
"FromFull": {
"Email": "dart-zzzzz@yandex.ru",
"Name": "Dart Zzzzz"
},
"To": "ad8a4d0842c486355a33a7f019caab51@inbound.icommapp.com",
"ToFull": [
{
"Email": "ad8a4d0842c486355a33a7f019caab51@inbound.icommapp.com",
"Name": ""
}
],
"CcFull": [],
"Cc": "",
"ReplyTo": "",
"OriginalRecipient": "ad8a4d0842c486355a33a7f019caab51@inbound.icommapp.com",
"Subject": "Тест.",
"Date": "Thu, 13 Feb 2014 17:48:22 +0300",
"MailboxHash": "",
"Tag": "",
"Attachments": [
{
"Name": "myimage.png",
"ContentID": "myimage.png@01CE7342.75E71F80",
"ContentType": "image/png",
"ContentLength": 4096
},
{
"Name": "mypaper.doc",
"ContentID": "",
"ContentType": "application/msword",
"ContentLength": 16384
}
],
"MessageID": "cc5727a0-ea30-4e79-baea-aa43c9628ac4",
"Status": "Blocked"
}
]
}

Messages API

Inbound message details

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/messages/inbound/{messageid}/details

Example request with curl

curl "https://api.trx.icommarketing.com/messages/inbound/{messageid}/details" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Response

From	string	The sender email address.
FromName	name	The sender name.
FromFull	object	Object that contains sender email address and name.
To	string	List of objects that contain To recipients.
ToFull	array	Object that contains the To address and name.
CcFull	array	Object that contains the Cc address and name.
Cc	string	List of objects that contain Cc recipients.
ReplyTo	string	Reply to override email address.
OriginalRecipient	string	Receiver (RCPT TO) address this webhook is for.
Subject	string	Email subject
Date	string	Timestamp
MailboxHash	string	Custom hash that the email was sent to.
TextBody	string	Text body of the message.
HtmlBody	string	Html body of the message.
Tag	string	Tags associated with this message.
Headers	array	List of objects that each represent a header name and value.
Attachments	array	List of objects that each represent an attachment.
MessageID	string	Unique ID of the message.
BlockedReason	string	Reason message was blocked.
Status	string	Status of message in your icomm activity.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"From": "dart-zzzzz@yandex.ru",
"FromName": "Dart Zzzzz",
"FromFull": {
"Email": "dart-zzzzz@yandex.ru",
"Name": "Dart Zzzzz"
},
"To": "ad8a4d0842c486355a33a7f019caab51@inbound.icommapp.com",
"ToFull": [
{
"Email": "ad8a4d0842c486355a33a7f019caab51@inbound.icommapp.com",
"Name": ""
}
],
"CcFull": [],
"Cc": "",
"ReplyTo": "",
"OriginalRecipient": "ad8a4d0842c486355a33a7f019caab51@inbound.icommapp.com",
"Subject": "Тест.",
"Date": "Thu, 13 Feb 2014 17:48:22 +0300",
"MailboxHash": "",
"TextBody": "stuff stuff.",
"HtmlBody": "",
"Tag": "",
"Headers": [
{
"Name": "X-Spam-Checker-Version",
"Value": "SpamAssassin 3.3.1 (2010-03-16) on sc-ord-inbound1"
},
{
"Name": "X-Spam-Status",
"Value": "No"
},
{
"Name": "X-Spam-Score",
"Value": "0.7"
},
{
"Name": "X-Spam-Tests",
"Value": "DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FROM,FSL_HELO_BARE_IP_2,RCVD_IN_DNSWL_LOW,SPF_PASS"
},
{
"Name": "Received-SPF",
"Value": "Pass (sender SPF authorized) identity=mailfrom; client-ip=95.108.130.92; helo=forward14.mail.yandex.net; envelope-from=dart-zzzzz@yandex.ru; receiver=ad8a4d0842c486355a33a7f019caab51@inbound.icommapp.com"
},
{
"Name": "DKIM-Signature",
"Value": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=yandex.ru; s=mail;t=1392302902; bh=4mN45y6KsGBYQjvZYsA49+gc9iuptslitnW5OR+Gg0M=;h=From:To:Subject:Date;b=StRtIzi3pvGDORwJkDc49RGqcgvlFvUEqAXi8RoHGu3LvHQmZs0F2pRdqc5UYt1gO OvLSKhlDslDkACdSJQAkj6EF99gXgiLItWo7hNfbv03qDlIq27f8vCZN5Uw0DY5shQ mVatnZbP/L01YP1pTXQONaalDFJ4ByRjjrWDrFVI="
},
{
"Name": "Envelope-From",
"Value": "Dart-zzzzz@yandex.ua"
},
{
"Name": "MIME-Version",
"Value": "1.0"
},
{
"Name": "Message-Id",
"Value": "<51351392302902@web19j.yandex.ru>"
},
{
"Name": "X-Mailer",
"Value": "Yamail [ http://yandex.ru ] 5.0"
},
{
"Name": "Content-Transfer-Encoding",
"Value": "8bit"
}
],
"Attachments": [
{
"Name": "myimage.png",
"ContentID": "myimage.png@01CE7342.75E71F80",
"ContentType": "image/png",
"ContentLength": 4096
},
{
"Name": "mypaper.doc",
"ContentID": "",
"ContentType": "application/msword",
"ContentLength": 16384
}
],
"MessageID": "cc5727a0-ea30-4e79-baea-aa43c9628ac4",
"BlockedReason": "Inbound request blocked by domain rule: badsender@example.com",
"Status": "Blocked"
}

Messages API

Bypass rules for a blocked inbound message

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

put

/messages/inbound/{messageid}/bypass

Example request with curl

curl "https://api.trx.icommarketing.com/messages/inbound/{messageid}/bypass" \
  -X PUT \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Response

ErrorCode	integer	API Error Codes
Message	string	The result of trying to bypass the blocked message.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  ErrorCode: 0
  Message: "Successfully bypassed message: 792a3e9d-0078-40df-a6b0-fc78f87bf277."
}

Messages API

Retry a failed inbound message for processing

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

put

/messages/inbound/{messageid}/retry

Example request with curl

curl "https://api.trx.icommarketing.com/messages/inbound/{messageid}/retry" \
  -X PUT \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d ""

Response

ErrorCode	integer	API Error Codes
Message	string	The result of trying to bypass the blocked message.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  ErrorCode: 0
  Message: "Successfully rescheduled failed message: 041e3d29-737d-491e-9a13-a94d3rjkjka13."
}

Messages API

Message opens

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/messages/inbound/{messageid}/retry

Example request with curl

curl "https://api.trx.icommarketing.com/messages/outbound/opens?recipient=john.doe@yahoo.com&count=50&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

count	required Number of messages to return per request. Max 500. Count + Offset cannot exceed 10,000 messages.
offset	required Number of messages to skip. Count + Offset cannot exceed 10,000 messages.
recipient	Filter by To, Cc, Bcc
tag	Filter by tag
messagestream	Filter by message stream ID. If not provided, search will default to the `outbound` transactional stream.
client_name	Filter by client name, i.e. Outlook, Gmail
client_company	Filter by company, i.e. Microsoft, Apple, Google
client_family	Filter by client family, i.e. OS X, Chrome
os_name	Filter by full OS name and specific version, i.e. OS X 10.9 Mavericks, Windows 7
os_family	Filter by kind of OS used without specific version, i.e. OS X, Windows
os_company	Filter by company which produced the OS, i.e. Apple Computer, Inc., Microsoft Corporation
platform	Filter by platform, i.e. webmail, desktop, mobile
country	Filter by country messages were opened in, i.e. Denmark, Russia
region	Filter by full name of region messages were opened in, i.e. Moscow, New York
city	Filter by full name of city messages were opened in, i.e. Minneapolis, Philadelphia

Response

Consistent fields

These fields will always be returned.

TotalCount	integer	Indicates how many opens match the search criteria you specified. This can be more than what is fetched by a single call.
Opens	array	List of documents that each represent a single email open. Note that a single open is bound to a single recipient, so if the same message was sent to two recipients and both of them opened it, that will be represented by two entries in this array.
UserAgent	string	Full `user-agent` header passed by the client software to icomm. Icomm will fill in the `Platform` `Client` and `OS` fields based on this.
MessageID	string	Unique ID of the message.
MessageStream	string	The outbound sending message stream for the message.
ReceivedAt	string	Timestamp of when the message was opened

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"TotalCount": 1,
"Opens": [
{
"Client": {
"Name": "Chrome 34.0.1847.131",
"Company": "Google Inc.",
"Family": "Chrome"
},
"OS": {
"Name": "OS X 10.7 Lion",
"Company": "Apple Computer, Inc.",
"Family": "OS X"
},
"Platform": "WebMail",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.131 Safari/537.36",
"Geo": {
"CountryISOCode": "RS",
"Country": "Serbia",
"RegionISOCode": "VO",
"Region": "Autonomna Pokrajina Vojvodina",
"City": "Novi Sad",
"Zip": "21000",
"Coords": "45.2517,19.8369",
"IP": "188.2.95.4"
},
"MessageID": "927e56d4-dc66-4070-bbf0-1db76c2ae14b",
"MessageStream": "outbound",
"ReceivedAt": "2014-04-30T05:04:23.8768746-04:00",
"Tag": "welcome-user",
"Recipient": "john.doe@yahoo.com"
}
]
}

Additional fields

When reading the resulting JSON, please allow for any of the following fields to be missing. If icomm could not obtain that part of the information, the field will not be present in the resulting JSON.

Client	object	Shows the email client (or browser) used to open the email. `Name` `company` and `family` are described in the parameters specification for this endpoint
OS	object	Shows the operating system used to open the email.
Platform	string	Shows what platform was used to open the email. `WebMail` `Desktop` `Mobile` `Unknown`
Geo	object	Contains IP of the recipient’s machine where the email was opened and the information based on that IP - geo coordinates (Coords) and country, region, city and zip.

Messages API

Opens for a single message

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/messages/outbound/opens/{messageid}

Example request with curl

curl "https://api.trx.icommarketing.com/messages/outbound/opens/{messageid}?count=10&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Response

Consistent fields

These fields will always be returned.

TotalCount	integer	Icomm API only stores the first open, so TotalCount will always equal "1". The Open Webhook will post each individual open if needed.
Opens	array	List of documents that each represent a single email open. Note that a single open is bound to a single recipient, so if the same message was sent to two recipients and both of them opened it, that will be represented by two entries in this array.
UserAgent	string	Full `user-agent` header passed by the client software to icomm. Icomm will fill in the `Platform` `Client` and `OS` fields based on this.
MessageID	string	Unique ID of the message.
MessageStream	string	The outbound sending message stream for the message.
ReceivedAt	string	Timestamp of when the message was opened.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"TotalCount": 1,
"Opens": [
{
"Client": {
"Name": "Chrome 34.0.1847.131",
"Company": "Google Inc.",
"Family": "Chrome"
},
"OS": {
"Name": "OS X 10.7 Lion",
"Company": "Apple Computer, Inc.",
"Family": "OS X"
},
"Platform": "WebMail",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.131 Safari/537.36",
"Geo": {
"CountryISOCode": "RS",
"Country": "Serbia",
"RegionISOCode": "VO",
"Region": "Autonomna Pokrajina Vojvodina",
"City": "Novi Sad",
"Zip": "21000",
"Coords": "45.2517,19.8369",
"IP": "188.2.95.4"
},
"MessageID": "927e56d4-dc66-4070-bbf0-1db76c2ae14b",
"MessageStream": "outbound",
"ReceivedAt": "2014-04-30T05:04:23.8768746-04:00",
"Tag": "welcome-user",
"Recipient": "john.doe@yahoo.com"
}
]
}

Additional fields

Client	object	Shows the email client (or browser) used to open the email. `Name` `company` and `family` are described in the parameters specification for this endpoint
OS	object	Shows the operating system used to open the email.
Platform	string	Shows what platform was used to open the email. `WebMail` `Desktop` `Mobile` `Unknown`
Geo	object	Contains IP of the recipient’s machine where the email was opened and the information based on that IP - geo coordinates (Coords) and country, region, city and zip.

Messages API

Message clicks

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/messages/outbound/clicks

Example request with curl

curl "https://api.trx.icommarketing.com/messages/outbound/clicks?recipient=john.doe@yahoo.com&count=50&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

count	required Number of message clicks to return per request. Max 500.
offset	required Number of clicks to skip
recipient	Filter by To, Cc, Bcc
tag	Filter by tag
client_name	Filter by client name, i.e. Outlook, Gmail
client_company	Filter by company, i.e. Microsoft, Apple, Google
client_family	Filter by client family, i.e. OS X, Chrome
os_name	Filter by full OS name and specific version, i.e. OS X 10.9 Mavericks, Windows 7
os_family	Filter by kind of OS used without specific version, i.e. OS X, Windows
os_company	Filter by company which produced the OS, i.e. Apple Computer, Inc., Microsoft Corporation
platform	Filter by platform, i.e. webmail, desktop, mobile
country	Filter by country messages were clicked in, i.e. Denmark, Russia
region	Filter by full name of region messages were clicked in, i.e. Moscow, New York
city	Filter by full name of city messages were clicked in, i.e. Minneapolis, Philadelphia
messagestream	Filter by message stream ID. If not provided, message will default to the `outbound` transactional stream.

Response

Consistent fields

These fields will always be returned.

TotalCount	integer	Indicates how many clicks match the search criteria you specified. This can be more than what is fetched by a single call.
Clicks	array	List of events that each represent a single email click. Note that a single click is bound to a single recipient and unique link, so if the same message was sent to two recipients and both of them clicked links in the message each will be included in the array.
UserAgent	string	Full `user-agent` header passed by the client software to icomm. Icomm will fill in the `Platform` `Client` and `OS` fields based on this.
MessageID	string	Unique ID of the message.
ReceivedAt	string	Timestamp of when the link was clicked.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"TotalCount": 1,
"Clicks": [
{
"ClickLocation" : "HTML",
"Client": {
"Name": "Chrome 34.0.1847.131",
"Company": "Google Inc.",
"Family": "Chrome"
},
"OS": {
"Name": "OS X 10.7 Lion",
"Company": "Apple Computer, Inc.",
"Family": "OS X"
},
"Platform": "WebMail",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.131 Safari/537.36",
"OriginalLink" : "https://example.com",
"Geo": {
"CountryISOCode": "RS",
"Country": "Serbia",
"RegionISOCode": "VO",
"Region": "Autonomna Pokrajina Vojvodina",
"City": "Novi Sad",
"Zip": "21000",
"Coords": "45.2517,19.8369",
"IP": "188.2.95.4"
},
"MessageID": "927e56d4-dc66-4070-bbf0-1db76c2ae14b",
"MesssageStream": "Outbound",
"ReceivedAt": "2014-04-30T05:04:23.8768746-04:00",
"Tag": "welcome-user",
"Recipient": "john.doe@yahoo.com"
}
]
}

Additional fields

Client	object	Shows the email client (or browser) used to open the email. `Name` `company` and `family` are described in the parameters specification for this endpoint
OS	object	Shows the operating system used to open the email.
Platform	string	Shows what platform was used to open the email. `WebMail` `Desktop` `Mobile` `Unknown`
Geo	object	Contains IP of the recipient’s machine where the email was opened and the information based on that IP - geo coordinates (Coords) and country, region, city and zip.

Messages API

Clicks for a single message

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found from the API Tokens tab under your icomm server.

get

/messages/outbound/clicks/{messageid}

Example request with curl

curl "https://api.trx.icommarketing.com/messages/outbound/clicks/{messageid}?count=10&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

count	required Number of message clicks to return per request. Max 500.
offset	required Number of messages to skip

Response

Consistent fields

These fields will always be returned.

TotalCount	integer	Indicates how many clicks match the search criteria you specified. This can be more than what is fetched by a single call.
Clicks	array	List of events that each represent a single email click. Note that a single click is bound to a single recipient and unique link, so if the same message was sent to two recipients and both of them clicked links in the message each will be included in the array.
UserAgent	string	Full `user-agent` header passed by the client software to icomm. Icomm will fill in the `Platform` `Client` and `OS` fields based on this.
MessageID	string	Unique ID of the message.
MessageStream	string	The outbound sending message stream for the message.
ReceivedAt	string	Timestamp of when the link was clicked.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"TotalCount": 1,
"Clicks": [
{
"ClickLocation" : "HTML",
"Client": {
"Name": "Chrome 34.0.1847.131",
"Company": "Google Inc.",
"Family": "Chrome"
},
"OS": {
"Name": "OS X 10.7 Lion",
"Company": "Apple Computer, Inc.",
"Family": "OS X"
},
"OriginalLink" : "https://example.com",
"Platform": "WebMail",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.131 Safari/537.36",
"Geo": {
"CountryISOCode": "RS",
"Country": "Serbia",
"RegionISOCode": "VO",
"Region": "Autonomna Pokrajina Vojvodina",
"City": "Novi Sad",
"Zip": "21000",
"Coords": "45.2517,19.8369",
"IP": "188.2.95.4"
},
"MessageID": "927e56d4-dc66-4070-bbf0-1db76c2ae14b",
"MessageStream": "outbound",
"ReceivedAt": "2014-04-30T05:04:23.8768746-04:00",
"Tag": "welcome-user",
"Recipient": "john.doe@yahoo.com"
}
]
}

Additional fields

Client	object	Shows the email client (or browser) used to open the email. `Name` `company` and `family` are described in the parameters specification for this endpoint
OS	object	Shows the operating system used to open the email.
Platform	string	Shows what platform was used to open the email. `WebMail` `Desktop` `Mobile` `Unknown`
Geo	object	Contains IP of the recipient’s machine where the email was opened and the information based on that IP - geo coordinates (Coords) and country, region, city and zip.

Stats API

Lets you get all of the statistics of your outbound emails for a specific server. These statistics are stored permanently and do not expire. All stats use EST timezone.

Stats API

Get outbound overview

Gets a brief overview of statistics for all of your outbound email.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the API Tokens tab under your icomm server.

get

/stats/outbound

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Sent	integer	Number of sent emails.
Bounced	integer	Number of bounced emails.
SMTPApiErrors	integer	Number of SMTP errors.
BounceRate	double	Bounce rate percentage calculated by total sent.
SpamComplaints	integer	Number of spam complaints received.
SpamComplaintsRate	double	Spam complaints percentage calculated by total sent.
Opens	integer	Number of opens.
UniqueOpens	integer	Number of unique opens.
TotalClicks	integer	Total number of clicks from all tracked links.
UniqueLinksClicked	integer	Total number of unique clicks from all tracked links.
TotalTrackedLinksSent	integer	Total number of tracked links sent in emails.
Tracked	integer	Number of emails sent with either Link or Open Tracking enabled. An email that has both types of tracking enabled will only increase this total by 1.
WithLinkTracking	integer	Number of emails sent with Link Tracking enabled.
WithOpenTracking	integer	Number of emails sent with Open Tracking enabled.
WithClientRecorded	integer	Number of emails where the client was successfully tracked.
WithPlatformRecorded	integer	Number of emails where platform was successfully tracked.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Sent": 615,
"Bounced": 64,
"SMTPApiErrors": 25,
"BounceRate": 10.406,
"SpamComplaints": 10,
"SpamComplaintsRate": 1.626,
"Opens": 166,
"UniqueOpens": 26,
"Tracked": 111,
"WithLinkTracking": 90,
"WithOpenTracking": 51,
"TotalTrackedLinksSent": 60,
"UniqueLinksClicked": 30,
"TotalClicks": 72,
"WithClientRecorded": 14,
"WithPlatformRecorded": 10
}

Stats API

Get sent counts

Gets a total count of emails you’ve sent out.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

/stats/outbound/sends

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/sends?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days	array	List of objects that each represent sent counts by date.
Sent	integer	Number of sent emails.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Days": [
{
"Date": "2014-01-01",
"Sent": 140
},
{
"Date": "2014-01-02",
"Sent": 160
},
{
"Date": "2014-01-04",
"Sent": 50
},
{
"Date": "2014-01-05",
"Sent": 115
}
],
"Sent": 615
}

Stats API

Get bounce counts

Gets total counts of emails you’ve sent out that have been returned as bounced.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

/stats/outbound/bounces

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/bounces?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days	array	List of objects that each represent bounce counts by date.
HardBounce	integer	Indicates total number of hard bounces.
SMTPApiError	integer	Indicates total number of SMTP errors.
SoftBounce	integer	Indicates total number of soft bounces.
Transient	integer	Indicates total number of transient bounces.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Days": [
{
"Date": "2014-01-01",
"HardBounce": 12,
"SoftBounce": 36
},
{
"Date": "2014-01-03",
"Transient": 7
},
{
"Date": "2014-01-04",
"Transient": 4
},
{
"Date": "2014-01-05",
"SMTPApiError": 25,
"Transient": 5
}
],
"HardBounce": 12,
"SMTPApiError": 25,
"SoftBounce": 36,
"Transient": 16
}

Stats API

Get spam complaints

Gets a total count of recipients who have marked your email as spam.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

/stats/outbound/spam

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/spam?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days	array	List of objects that each represent spam complaint counts by date.
SpamComplaint	integer	Number of spam complaints received.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Days": [
{
"Date": "2014-01-01",
"SpamComplaint": 2
},
{
"Date": "2014-01-02",
"SpamComplaint": 3
},
{
"Date": "2014-01-05",
"SpamComplaint": 5
}
],
"SpamComplaint": 10
}

Stats API

Get tracked email counts

Gets a total count of emails you’ve sent with open tracking or link tracking enabled.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

/stats/outbound/tracked

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/tracked?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days	array	List of objects that each represent tracked email counts by date.
Tracked	integer	Number of emails sent with either Link or Open Tracking enabled. An email that has both types of tracking enabled will only increase this total by 1.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Days": [
{
"Date": "2014-01-01",
"Tracked": 24
},
{
"Date": "2014-01-02",
"Tracked": 26
},
{
"Date": "2014-01-03",
"Tracked": 15
},
{
"Date": "2014-01-04",
"Tracked": 15
},
{
"Date": "2014-01-05",
"Tracked": 31
}
],
"Tracked": 111
}

Stats API

Get email open counts

Gets total counts of recipients who opened your emails. This is only recorded when open tracking is enabled for that email.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

/stats/outbound/opens

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/opens?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days	array	List of objects that each represent tracked email counts by date.
Opens	integer	Indicates total number of opened emails. This total includes recipients who opened your email multiple times.
Unique	integer	Indicates total number of uniquely opened emails.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Days": [
{
"Date": "2014-01-01",
"Opens": 44,
"Unique": 4
},
{
"Date": "2014-01-02",
"Opens": 46,
"Unique": 6
},
{
"Date": "2014-01-03",
"Opens": 25,
"Unique": 5
},
{
"Date": "2014-01-04",
"Opens": 25,
"Unique": 5
},
{
"Date": "2014-01-05",
"Opens": 26,
"Unique": 6
}
],
"Opens": 166,
"Unique": 26
}

Stats API

Get email platform usage

Gets an overview of the platforms used to open your emails. This is only recorded when open tracking is enabled for that email.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

/stats/outbound/opens/platforms

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/opens/platforms?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days	array	List of objects that each represent email usage by date.
Desktop	integer	Indicates total number of desktop users.
Mobile	integer	Indicates total number of mobile users.
Unknown	integer	Indicates total number of users who’s platforms could not be determined.
WebMail	integer	Indicates total number of users on web email platforms.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Days": [
{
"Date": "2014-01-01",
"Desktop": 1,
"WebMail": 1
},
{
"Date": "2014-01-02",
"Mobile": 2,
"WebMail": 1
},
{
"Date": "2014-01-04",
"Desktop": 3,
"Unknown": 2
}
],
"Desktop": 4,
"Mobile": 2,
"Unknown": 2,
"WebMail": 2
}

Stats API

Get email client usage

Gets an overview of the email clients used to open your emails. This is only recorded when open tracking is enabled for that email.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

/stats/outbound/opens/emailclients

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/opens/emailclients?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days	array	List of objects that each represent email client usage by date.
Client (e.g. Apple Mail)	integer	Indicates total number of users for that given email client.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Days": [
{
"Date": "2014-01-01",
"Apple Mail": 1,
"Outlook 2010": 1
},
{
"Date": "2014-01-02",
"Apple Mail": 1,
"Outlook 2010": 2
},
{
"Date": "2014-01-04",
"Apple Mail": 4,
"Outlook 2010": 5
}
],
"Apple Mail": 6,
"Outlook 2010": 8
}

Stats API

Get email read times

Gets the length of time that recipients read emails along with counts for each time. This is only recorded when open tracking is enabled for that email. Read time tracking stops at 20 seconds, so any read times above that will appear in the 20s+ field.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

stats/outbound/opens/readtimes

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/opens/readtimes?tag=&fromdate=&todate=" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01

Stats API

Get click counts

Gets total counts of unique links that were clicked.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

/stats/outbound/clicks

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/clicks?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days	array	List of objects that each represent clicks by date.
Clicks	integer	Indicates total number of clicked links. This total includes recipients who clicked links in your email multiple times.
Unique	integer	Indicates total number of unique links that were clicked. Links are considered unique for each recipient, per email. However the same url in both the text or html bodies will be treated as the same link.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Days": [
{
"Date": "2014-01-01",
"Clicks": 44,
"Unique": 4
},
{
"Date": "2014-01-02",
"Clicks": 46,
"Unique": 6
},
{
"Date": "2014-01-03",
"Clicks": 25,
"Unique": 5
},
{
"Date": "2014-01-04",
"Clicks": 25,
"Unique": 5
},
{
"Date": "2014-01-05",
"Clicks": 26,
"Unique": 6
}
],
"Clicks": 166,
"Unique": 26
}

Stats API

Get browser usage

Gets an overview of the browsers used to open links in your emails. This is only recorded when Link Tracking is enabled for that email.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

/stats/outbound/clicks/browserfamilies

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/clicks/browserfamilies?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days	array	List of objects that each represent browser usage by date.
Client (e.g. Safari mobile)	integer	Indicates total number of of times the given browser was used to open a tracked link in your emails.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Days": [
{
"Date": "2014-01-01",
"Google Chrome": 1,
"Safari mobile": 1
},
{
"Date": "2014-01-02",
"Google Chrome": 1,
"Safari mobile": 2
},
{
"Date": "2014-01-04",
"Google Chrome": 4,
"Safari mobile": 5
}
],
"Google Chrome": 6,
"Safari mobile": 8
}

Stats API

Get browser platform usage

Gets an overview of the browser platforms used to open your emails. This is only recorded when Link Tracking is enabled for that email.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

/stats/outbound/clicks/platforms

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/clicks/platforms?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days	array	List of objects that each represent browser usage by date.
Desktop	integer	Indicates total number of clicks that opened in desktop browsers.
Mobile	integer	Indicates total number of clicks that opened in mobile browsers.
Unknown	integer	Indicates total number of clicks where the browser platform could not be determined.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Days": [
{
"Date": "2014-01-01",
"Desktop": 1
},
{
"Date": "2014-01-02",
"Mobile": 2
},
{
"Date": "2014-01-04",
"Desktop": 3,
"Unknown": 2
}
],
"Desktop": 4,
"Mobile": 2,
"Unknown": 2
}

Stats API

Get click location

Gets an overview of which part of the email links were clicked from (HTML or Text). This is only recorded when Link Tracking is enabled for that email.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the Credentials tab under your icomm server.

get

/stats/outbound/clicks/location

Example request with curl

curl "https://api.trx.icommarketing.com/stats/outbound/clicks/location?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

tag	Filter by tag
fromdate	Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate	Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream	Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days	array	List of objects that each represent browser usage by date.
HTML	integer	Indicates total number of clicks that were from links in the HTML content of the email.
Text	integer	Indicates total number of clicks that were from links in the text content of the email.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"Days": [
{
"Date": "2014-01-01",
"HTML": 1
},
{
"Date": "2014-01-02",
"Text": 2
},
{
"Date": "2014-01-04",
"HTML": 3,
"Text": 2
}
],
"HTML": 4,
"Text": 4
}

Suppressions API

This endpoint allows you to manage view, create, and delete suppressions in your Message Stream. If an address is suppressed it means it's not currently active for sending to. Deleting a HardBounce suppression is the equivalent of reactivating the associated Bounce.

Suppressions API

Suppression dump

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the API Tokens tab under your icomm server.

get

/message-streams/{stream_id}/suppressions/dump

Example request with curl

curl "https://api.trx.icommarketing.com/message-streams/{stream_id}/suppressions/dump?origin=recipient&fromdate=2019-12-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

SuppressionReason	Filter by suppression reason. Possible options: `HardBounce`, `SpamComplaint`, `ManualSuppression`.
Origin	Filter by origin of how the address was added to suppression list. Possible options: `Recipient`, `Customer`, `Admin`.
todate	Filter suppressions up to the date specified (inclusive). e.g. 2020-02-01.
fromdate	Filter suppressions up to the date specified (inclusive). e.g. 2020-02-01.
EmailAddress	Filter by email address.

Response

Suppressions	array	List of objects that each represent a single suppression.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{  
"Suppressions":[
{  
"EmailAddress":"address@wildbit.com",
"SuppressionReason":"ManualSuppression",
"Origin": "Recipient",
"CreatedAt":"2019-12-17T08:58:33-05:00"
},
{  
"EmailAddress":"bounce.address@wildbit.com",
"SuppressionReason":"HardBounce",
"Origin": "Recipient",
"CreatedAt":"2019-12-17T08:58:33-05:00"
},
{  
"EmailAddress":"spam.complaint.address@wildbit.com",
"SuppressionReason":"SpamComplaint",
"Origin": "Recipient",
"CreatedAt":"2019-12-17T08:58:33-05:00"
}
]
}

Suppressions API

Create a Suppression

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the API Tokens tab under your icomm server.

/message-streams/{stream_id}/suppressions

Example request with curl

curl "https://api.trx.icommarketing.com/message-streams/{stream_id}/suppressions" \
  -X POST \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"\
  -d '{
  "Suppressions": [{
      "EmailAddress": "good.address@wildbit.com"
    },
    {
      "EmailAddress": "spammy.address@wildbit.com"
    },
    {
      "EmailAddress": "invalid-email-address"
    }
  ]
}'

Body format

Suppressions	array	required An array that will contain that email addresses to create a suppression on. Max of 50 suppressions that can be created in one call.
EmailAddress	string	The email address to request suppression creation on.

Example body format

{  
"Suppressions":[
{  
"EmailAddress":"good.address@wildbit.com"
},
{  
"EmailAddress":"spammy.address@wildbit.com"
},
{  
"EmailAddress":"invalid-email-address"
}
]  
}

Response

Suppressions	array	List that represent suppressions that were called for creation.
EmailAddress	string	An email address that the suppression creation was requested on.
Status	string	Status of suppression creation request. Possible values: `Failed`, `Suppressed`.
Message	string	If address cannot be suppressed (Status: `Failed`), the cause for failure is listed. If suppression is created, (Status: `Suppressed`) message is null.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{  
"Suppressions":[
{  
"EmailAddress":"good.address@wildbit.com",
"Status":"Suppressed",
"Message": null
},
{  
"EmailAddress":"spammy.address@wildbit.com",
"Status":"Failed",
"Message": "You do not have the required authority to change this suppression."
},
{  
"EmailAddress":"invalid-email-address",
"Status":"Failed",
"Message": "An invalid email address was provided."
}
]  
}

Suppressions API

Delete a Suppression

SpamComplaint suppressions cannot be deleted.

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the API Tokens tab under your icomm server.

/message-streams/{stream_id}/suppressions/delete

Example request with curl

curl "https://api.trx.icommarketing.com/message-streams/{stream_id}/suppressions/delete" \
  -X POST \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d '{
  "Suppressions": [
    {
      "EmailAddress": "bounced.address@wildbit.com"
    },
    {
      "EmailAddress": "not.suppressed@wildbit.com"
    },
    {
      "EmailAddress": "spammy.address@wildbit.com"
    }
  ]
}'

Body format

Suppressions	array	required An array of email addresses to delete a suppression on. Max of 50 suppressions that can be removed in one call.
EmailAddress	string	The email address to request suppression deletion on.

Example body format

{  
"Suppressions":[  
{  
"EmailAddress":"good.address@wildbit.com"
},
{  
"EmailAddress":"not.suppressed@wildbit.com"
},
{  
"EmailAddress":"spammy.address@wildbit.com"
}
]
}

Response

Suppressions	array	List that each represent suppressions that were called for deletion.
EmailAddress	string	An email address that the suppression deletion was requested on.
Status	string	Status of suppression deletion request. Possible values: `Failed`, `Deleted`.
Message	string	If address cannot be deleted (Status: Failed), the cause for failure is listed. If suppression deletion Status is successful (Status: `Deleted`) message is null.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{  
"Suppressions":[
{  
"EmailAddress":"good.address@wildbit.com",
"Status":"Deleted",
"Message": null
},
{  
"EmailAddress":"not.suppressed@wildbit.com",
"Status":"Deleted",
"Message": null
},
{  
"EmailAddress":"spammy.address@wildbit.com",
"Status":"Failed",
"Message": "You do not have the required authority to change this suppression."
}
]  
}

Inbound rules triggers API

Inbound rules triggers let you block messages from certain senders. You can block messages by email address or by domain.

Inbound rules triggers API

List inbound rule triggers

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level priveledges. This token can be found on the Credentials tab under your icomm server.

get

/triggers/inboundrules

Example request with curl

curl "https://api.trx.icommarketing.com/triggers/inboundrules?count=50&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Querystring parameters

count	required Number of records to return per request.
offset	required Number of records to skip.

Response

TotalCount	integer	Indicates how many triggers match the search criteria you specified.
InboundRules	array	List of objects that each represent each inbound rule.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"TotalCount": 3,
"InboundRules": [
{
"ID": 3,
"Rule": "someone@example.com"
},
{
"ID": 5,
"Rule": "badsender@example.com"
},
{
"ID": 7,
"Rule": "baddomain.com"
}
]
}

Inbound rules triggers API

Create an inbound rule trigger

Request headers

Content-Type	required application/json
Accept	required application/json
X-Trx-Api-Key	required This request requires server level privileges. This token can be found on the API Tokens tab under your icomm server.

/triggers/inboundrules

Example request with curl

curl "https://api.trx.icommarketing.com/triggers/inboundrules" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d '{
  "Rule": "someone@example.com"
}'

Body format

Rule	string	required Email address (or domain) that you would like to block from sending.

Example body format

{
"Rule": "someone@example.com",
}

Response

ID	integer	Unique ID of the trigger
Rule	string	Email address (or domain) that you would like to block from sending.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
"ID": 15,
"Rule": "someone@example.com"
}

Delete a single trigger

Request headers

Accept	required application/json
X-Trx-Api-Key	required This request requires server level priveledges. This token can be found on the Credentials tab under your icomm server.

delete

/triggers/inboundrules/{triggerid}

Example request with curl

curl "https://api.trx.icommarketing.com/triggers/inboundrules/{triggerid}" \
  -X DELETE \
  -H "Accept: application/json" \
  -H "X-Trx-Api-Key: server token"

Response

ErrorCode	integer	API Error Codes
Message	string	Response message

Example response

{
"ErrorCode": 0,
"Message": "Rule someone@example.com removed."
}

Sending email

Send a single email.

Sending emails through ICOMMKT is simple. Before you start, you need to determine how you want to send your emails. ICOMMKT has two ways of doing this:

REST API ICOMMKT’s REST API allows you to make HTTP requests to our service from your app.

SMTP If you’re already using SMTP to send your emails, this makes migration a breeze. Simply point your existing configuration over to ICOMMKT’s servers and we’ll handle the rest.

Send a single email

Sending single emails through ICOMMKT is as simple as sending an HTTP POST request to our /email endpoint with the JSON message attached to the body.

/email

Example request with curl

curl " https://api.icommktapp.com/email " \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d "{ From: 'sender@example.com', To: 'receiver@example.com', Subject: 'ICOMMKT test', HtmlBody: '<html><body><strong>Hello</strong> dear ICOMMKT user.</body></html>' }" \

Authentication headers

In order to authenticate yourself to the service, you need to use the X-Trx-Api-Key header for authentication and authorization. Each ICOMMKT server has its own API token, allowing you to isolate access and data for each application that connects to ICOMMKT.

The header name and value are case insensitive. Should you execute the request with wrong or missing headers, you will receive an HTTP Response 401 (Unauthorized).

Testing

For testing purposes, ICOMMKT lets you send test emails that won’t actually get delivered to the recipient. This method is typically used to verify that your data is valid. You can do this by passing ICOMMKT_API_TEST as your server API token.

Example header

X-Trx-Api-Key: server token

JSON message format

JSON messages are passed in the body of the HTTP POST request. The From and To fields are able to accept name, in the format of John Doe email@example.com. You can provide HtmlBody for HTML formatted messages, TextBody for plain text, or include both for multipart. Multipart sends HTML with a text version for clients that don’t support HTML. Passing headers is optional.

• You must have a registered and confirmed sender signature with the sender email. Otherwise you will receive an HTTP Response 422 (Unprocessable Entity).

• It’s possible to override the Name in the sender signature through the API. This is useful if you want to use member’s information in the email while keeping your From email address. Just pass the name into the From field "From": "John Smith sender@example.com"

• You can pass multiple recipient addresses in the To, Cc, and Bcc fields. Multiple addresses are comma separated and have a limit of 50 max recipients per message. This means that all receipients(To, Cc, and Bcc) are totaled and not allowed to exceed 50.

• You can categorize outgoing email using the Tag property. This enables you to get detailed statistics for all of your tagged emails. Only one tag may be used for each message.

• You can add metadata to an email using the Metadata property.

• For email addresses that have names or titles with punctuation, you should quote them as such: "To" : "\"Joe Receiver, jr\"receiver@example.com" .

• To send an email with a custom Message-ID header, you can pass the value you desire into the headers array: "Headers": [{"Name":"Message-ID", "Value": ""}].

Example JSON message format

{
 "From": "sender@example.com", 
"To": "receiver@example.com", 
"Cc": "copied@example.com", 
"Bcc": "blank-copied@example.com", 
"Subject": "ICOMMKT test", 
"Tag": "Invitation", 
"HtmlBody": "<b>Hello</b>",
"TextBody": "Hello",
"Metadata": {
    "Color": "blue",
    "Client-Id": "12345"
    },
"Headers": [
    {
    "Name": "CUSTOM-HEADER",
    "Value": "Value"
    }
  ],
"TrackOpens": "true", 
"TrackLinks": "HtmlOnly", 
 }

Tracking opens

There are three ways that you can activate open tracking for your emails:

• Track opens for your entire server.

• Track opens for a single email.

• Track opens for all emails with a specific tag.

Example API request with open tracking

{
  ...
 "TrackOpens": true
 }

Tracking links

You can enable Link Tracking to get information about the links your recipients click in your emails. Link tracking can be enabled on a per-message or per-server basis.

Example API request with link tracking

{
  ...
 "TrackLinks": "HtmlAndText"
 }

Attachments

Attachments are specified in the Attachments array in the JSON message. Individual attachments can then be stored as seperate objects within that array.

The Name field is the actual filename that will be displayed to the message recipient. To eliminate the possibility of spreading viruses or spyware we disallow certain file types:

Forbidden File Types: vbs, exe, bin, bat, chm, com, cpl, crt, hlp, hta, inf, ins, isp, jse, lnk, mdb, pcd, pif, reg, scr, sct, shs, vbe, vba, wsf, wsh, wsl, msc, msi, msp, mst.

The ContentType field is the MIME content type that email clients use to interpret the attachment.

The Content field stores the binary data for the file, which must be transmitted as a base64-encoded string. Most programming languages and libraries have this built in e.g. Java, .NET, PHP, Ruby.

Limitations:

• If a file type with a disallowed extension is detected, the message will be rejected — or if using SMTP you will receive an SMTP API bounce.

• Messages have some size limitations, which if exceeded will cause the message to be rejected:

• The TextBody and HtmlBody can be up to 5MB each.

• Total message size, including attachments, can be up to 10MB total. This can be as a single attachment, or many attachments that together don’t exceed 10MB. Please note: Base64-encoded strings may make your data seem larger than it really is, but ICOMMKT calculates the attachment size after Base64-encoding.

• We recommend sending emails with attachments from a background job, rather than as a response to a user action in the same web request handler. This is because an increased message size will take longer to submit to the ICOMMKT servers. Your users will love you for that!

Example message with attachments

{
  ...
 "Attachments": [
    {
        "Name": "readme.txt",
        "Content": "dGVzdCBjb250ZW50",
        "ContentType": "text/plain"
    },
    {
        "Name": "report.pdf",
        "Content": "dGVzdCBjb250ZW50",
        "ContentType": "application/octet-stream"
    }
  ]
 }

Inline image attachments

ICOMMKT also allows you to send inline images via HTML mesages. Images must be base64-encoded and the ContentID field must match the image's CID.

ICOMMKT will then automatically embed the images inline with your HTML as long as the CID tags match. NOTE: If you are referring to an attached image more than once in your message, it is only required to attach the image one time. ICOMMKT will use the image as often as it is referred to in your HTML markup. This will save bandwidth against the attachment size limit.

Example message with an inline image attachment

{
  ...
 "Attachments": [
    {
        "Name": "bacon.jpg",
        "Content": "/9j/4AAQSkZJRgABAgEAAAAAAAD/4",
        "ContentType": "image/jpeg",
        "ContentID": "cid:part1.01030607.06070005@gmail.com"
    }
  ]
 }

Example message with an inline image attachment

HTML inline image example

<img src="cid:part1.01030607.06070005@gmail.com">

Success

If all goes well, you will receive a JSON message looking like the example.

The MessageID field can be used to log in your system. It can then be used to associate the message you sent to a possible bounce that you obtained from a bounce webhook or the bounce API.

Example JSON response

{
  ...
 "Attachments": [
    {
        "ErrorCode": "0",
        "Message": "OK",
        "MessageID": "b7bc2f4a-e38e-4336-af7d-e6c392c2f817",
        "SubmittedAt": "2010-11-26T12:01:05.1794748-05:00",
        "To": "receiver@example.com"
    }
  ]
 }

API error codes

Whenever the ICOMMKT server detects an input error it will return an HTTP 422 status code along with a JSON object containing error details:

{
    "ErrorCode" : 405,
    "Message" : "details"
}

The ErrorCode field can be used to programmatically detect the type of error. Here are the supported error codes:

• 10 — Bad or missing API token Your request did not contain the correct API token in the header.

• 100 — Maintenance The ICOMMKT API is offline for maintenance.

• 300 — Invalid email request Validation failed for the email request JSON data that you provided.

• 400 — Sender Signature not found You’re trying to send email with a From address that doesn’t have a sender signature.

• 401 — Sender signature not confirmed You’re trying to send email with a From address that doesn’t have a confirmed sender signature.

• 402 — Invalid JSON The JSON data you provided is syntactically incorrect.

• 403 — Incompatible JSON The JSON data you provided is syntactically correct, but still doesn’t contain the fields we expect. Refer to the request's API reference page to see a list of required JSON body parameters.

• 405 — Not allowed to send Your account has run out of credits.

• 406 — Inactive recipient You tried to send email to a recipient that has been marked as inactive. Inactive recipients have either generated a hard bounce or a spam complaint. In this case, only hard bounce recipients can be reactivated by searching for them on your server’s Activity page and clicking the "Reactivate" button.

• 409 — JSON required Your HTTP request doesn’t have the Accept and Content-Type headers set to application/json.

• 410 — Too many batch messages Your batched request contains more than 500 messages.

• 411 — Forbidden attachment type The file type of the attachment isn’t allowed.

• 412 — Account is Pending The account that is associated with the send request is still pending approval. While an account is pending approval, email recipients must have the same domain as the one found in the email's from address.

• 413 — Account May Not Send The account that is associated with the send request is not approved for sending.

• 500 — Sender signature query exception You provided invalid querystring parameters in your request.

• 501 — Sender Signature not found by id We couldn’t locate the Sender Signature you’re trying to manage from the id passed in.

• 502 — No updated Sender Signature data received You didn’t pass in any valid updated Sender Signature data.

• 503 — You cannot use a public domain You tried to create a Sender Signature with a public domain which isn’t allowed.

• 504 — Sender Signature already exists You tried to create a Sender Signature that already exists on ICOMMKT.

• 505 — DKIM already scheduled for renewal The DKIM you tried to renew is already scheduled to be renewed.

• 506 — This Sender Signature already confirmed The signature you tried to resend a confirmation to has already been confirmed by a user.

• 507 — You do not own this Sender Signature This Sender Signature cannot be found using your credentials.

• 510 — This domain was not found We couldn’t locate the Domain you’re trying to manage from the id passed in.

• 511 — Invalid fields supplied You didn’t pass in any valid Domain data.

• 512 — Domain already exists You tried to create a Domain that already exists on your account.

• 513 — You do not own this Domain This Domain cannot be found using your credentials.

• 514 — Name is a required field to create a Domain You must set the Name parameter to create a Damain.

• 515 — Name field must be less than or equal to 255 characters The Name you have specified for this Domain is too long.

• 516 — Name format is invalid The Name you have specified for this Domain is formatted incorrectly.

• 520 — You are missing a required field to create a Sender Signature When creating a Sender Signature, you must supply a value for Name and FromEmail.

• 521 — A field in the Sender Signature request is too long View the Message property of the response for details.

• 522 — Value for field is invalid Value might be an invalid email address or domain. View the Message property of the response for details.

• 600 — Server query exception You provided invalid querystring parameters in your request.

• 601 — Server does not exist You tried to manage a server that doesn’t exist with your credentials.

• 602 — Duplicate Inbound Domain The Inbound Domain you specified is already in use on ICOMMKT.

• 603 — Server name already exists You tried to create a Server name that already exists in your list.

• 604 — You don’t have delete access You don’t have permission to delete Servers through the API.

• 605 — Unable to delete Server We couldn’t delete this Server.

• 606 — Invalid webhook URL The webhook URL you’re trying to use is invalid or contains an internal IP range.

• 607 — Invalid Server color The server color you specified isn't supported. Please choose either Purple, Blue, Turqoise, Green, Red, Orange, Yellow, or Grey for server color.

• 608 — Server name missing or invalid The Server name you provided is invalid or missing.

• 609 — No updated Server data received You didn’t pass in any valid updated Server data.

• 610 — Invalid MX record for Inbound Domain The Inbound Domain provided doesn’t have an MX record value of inbound.icommktapp.com.

• 611 — InboundSpamThreshold value is invalid Please use a number between 0 and 30 in incrememts of 5.

• 700 — Messages query exception You provided invalid querystring parameters in your request.

• 701 — Message doesn’t exist This message doesn’t exist.

• 702 — Could not bypass this blocked inbound message, please contact support There was a problem processing this bypass request. Please contact support to fix the issue.

• 703 — Could not retry this failed inbound message, please contact support There was a problem processing this retry request. Please contact support to fix the issue..

• 800 — Trigger query exception You provided invalid querystring parameters in your request.

• 801 — Trigger for this tag doesn’t exist You tried to manage a trigger that doesn’t exist in your server.

• 803 — Tag with this name already has trigger associated with it The server already has a trigger associated with the Tag name you provided.

• 808 — Name to match is missing MatchName property is required in request JSON body.

• 809 — No trigger data received You didn’t provide JSON body parameters in your request.

• 810 — This inbound rule already exists You tried to add a rule that already exists for thie server. Please choose a unique rule to add.

• 811 — Unable to remove this inbound rule, please contact support We weren't able to remove this rule from your server. Please contact support to resolve the issue.

• 812 — This inbound rule was not found The inbound rule you are trying to administer does not exist for this server.

• 813 — Not a valid email address or domain Please use a valid email address or valid domain to setup an inbound domain rule.

• 900 — Stats query exception You provided invalid querystring parameters in your request.

• 1000 — Bounces query exception You provided invalid querystring parameters in your request.

• 1001 — Bounce was not found The BounceID or MessageID you are searching with is invalid.

• 1002 — BounceID parameter required You must supply a BounceID to get the bounce dump.

• 1003 — Cannot activate bounce Certain bounces and SPAM complaints cannot be activated by the user.

• 1100 — Template query exception The value of a GET parameter for the request is not valid.

• 1101 — Template not found The TemplateId, LayoutTemplate, or Alias references a Template that does not exist, or is not associated with the Server specified for this request.

• 1105 — Template limit would be exceeded A Server may have up to 1,000 active templates, processing this request would exceed this limit.

• 1109 — No Template data received You didn’t provide JSON body parameters in your request.

• 1120 — A required Template field is missing A required field is missing from the body of the POST request.

• 1121 — Template field is too large One of the values of the request's body exceeds our size restrictions for that field.

• 1122 — A Templated field has been submitted that is invalid One of the fields of the request body is invalid.

• 1123 — A field was included in the request body that is not allowed A field is included in the request that will be ignored, or is not applicable to the endpoint to which it has been sent.

• 1125 — The template types don't match on the source and destination servers The template alias is a layout on one server and a standard template on the other. The templates cannot share the same alias.

• 1130 - The layout template cannot be deleted because it has dependent templates using it A layout cannot be deleted when there are associated templates using the layout.

• 1131 - The layout content placeholder must be present in the layout HTML and/or Text body exactly once A single content placeholder is required for every layout. The content placeholder cannot be present in a standard template.

Send batch emails

While ICOMMKT is focused on transactional email, we understand that developers with higher volumes or processing time constraints need to send their messages in batches. To facilitate this we provide a batching endpoint that permits you to send up to 500 well-formed ICOMMKT messages in a single API call.

The format of the batched message is a JSON array containing multiple message requests.

/email/batch

Example request with curl

curl " https://api.icommktapp.com/email/batch " \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Trx-Api-Key: server token" \
  -d "[{ From: 'sender@example.com', To: 'receiver1@example.com', Subject: 'ICOMMKT test #1', HtmlBody: '<html><body><strong>Hello</strong> dear ICOMMKT user.</body></html>' }, { From: 'sender@example.com', To: 'receiver2@example.com', Subject: 'ICOMMKT test #2', HtmlBody: '<html><body><strong>Hello</strong> dear ICOMMKT user.</body></html>' }]" \

Response

Similarly, you will receive a matching JSON array containing each response for the messages you sent in your batched call.

See a full list of API errors for more details.

Example JSON response


 [
    {
        "ErrorCode": "0",
        "Message": "OK",
        "MessageID": "b7bc2f4a-e38e-4336-af7d-e6c392c2f817",
        "SubmittedAt": "2010-11-26T12:01:05.1794748-05:00",
        "To": "receiver1@example.com"
    },
    {
        "ErrorCode": "0",
        "Message": "OK",
        "MessageID": "e2ecbbfc-fe12-463d-b933-9fe22915106d",
        "SubmittedAt": "2010-11-26T12:01:05.1794748-05:00",
        "To": "receiver2@example.com"
    }
  ]

Sending with SMTP

Already using SMTP in your application? You can instantly switch your current email delivery. This feature lets you use plain SMTP to send your messages and you only need to point to ICOMMKT's SMTP server.

Why use SMTP instead of the API?

Quite often you have your web application delivering emails using SMTP and a migration to ICOMMKT would require you to change your code. With SMTP access at your disposal, you can simply change a configuration setting in your application and instantly switch delivery to ICOMMKT.

How does it work?

Just as the REST API uses a server’s API token to authenticate the client, SMTP access is also configured per server. The outbound server settings page allows you to enable or disable SMTP access for a server.

After enabling access, you will be able to connect to smtp.trx.icommarketing.com using your server API token as both a user name and password. Our SMTP servers are now able to accept your messages and they will be routed to the ICOMMKT mail queue.

Connection details

Server - smtp.trx.icommarketing.com
Ports - 25, 2525, or 587
TLS - TLS is available via the STARTTLS SMTP extension. This establishes an encrypted connection to our SMTP server, and all credentials and content are encrypted while they are transmitted to us. We recommend you use TLS if possible.
Username/Password - Server API token Authentication Methods.

CRAM-MD5 - Protects just the authentication process, however the message content is still sent as plain text if TLS is not enabled.
DIGEST-MD5 - Protects just the authentication process, however the message content is still sent as plain text if TLS is not enabled.
PLAIN - When not combined with TLS, the username and password are sent in clear text. We do not recommend using this method without enabling TLS. However, some older SMTP clients may not support other authentication methods. Use with caution.
LOGIN - Similar to PLAIN method. We also make this available for compatibility with older SMTP clients. Use with caution.

Globally distributed SMTP servers

The SMTP servers that accept messages are globally distributed around the world. Since SMTP can be a chatty and slow protocol, we created multiple data centers in San Jose, Chicago, Virginia, Amsterdam and Singapore. Depending on your location you will be routed to the closest server for the fastest response times possible. For instance, if your application servers are in London, your messages will be automatically routed to our Amsterdam facility, resulting very low latency and faster performance for your application.

Differences from the REST API

The REST API is the primary API for the service and the SMTP endpoint is considered a migration route. Using SMTP access avoids big changes to your code base.

Many client libraries for the REST API offer advanced features such as retrying several times on network errors. That could help in cases where there is a temporary problem connecting to the ICOMMKT servers. The API also offers features such as batch sending for improved performance when sending many emails. Overall, the REST API will have less overhead when your application conmmunicates with ICOMMKT.

Another important benefit of the REST API is response codes. The REST API will immediately return a success or error message to your application upon receiving a message. For instance, if a recipient is deactivated due to hard bounce you will be notified when attempting to send a message. In addition, the response will provide a message-ID for tracking along with error codes to handle problems gracefully. The SMTP endpoint will accept all messages and log bounces for any errors it encounters, which are still accessible using our bounce webhooks or bounce API endpoint.

Tags support in SMTP

Tags can be used in SMTP messges, similar to the API. In order to use a tag for your message, you must include the tag in an SMTP header named X-PM-Tag. Most programming languages with SMTP modules include a method by which to add a custom tag to SMTP messages. Only one tag may be used per message.

X-PM-Tag : welcome-email

Tracking links

Link Tracking Options.

There are several variations of Link Tracking available from ICOMMKT. Depending on your requirements, you can choose from the following options:

None - No links will be replaced or tracked. This is the default setting for all messages and new and existing servers.
HtmlAndText - Links will be replaced in both HTML and Text bodies. Identical links in either body part will be considered the "same" link, and only count as one unique click, regardless of which body part the recipient clicks from.
HtmlOnly - Links will be replaced in only the HTMLBody. This is useful in some cases where you do not want to include encoded tracking links in the plain text of an email.
TextOnly - Links will be replaced in only the TextBody.

Setting the Tracking Type

After you have determined which type of Link Tracking you wish to use, you can enable it in several ways:

Server-level - You can set the TrackLinks property for each server where you wish to enable Link Tracking. This setting will be applied to all messages sent by the server. However, individual messages sent through the API or SMTP may override this setting.
Message-level (API) - You can set the TrackLinks property on each message you send through the API. This setting overrides the default setting for the server.
Message-level (SMTP) - You can set the X-PM-TrackLinks header on each message you send through SMTP. This setting overrides the default setting for the server.

Per-link opt-out

In some cases you may wish to exclude a link from tracking, even if the rest of the message's links should be tracked. To do this, you should add an additional data-pm-no-track attribute to your links in the HTMLBody of your emails. For example:

<a data-pm-no-track href="http://example.com"> Non-Tracked Link </a>

Note that this feature requires that the link be contained and ignored in HTML, but if you have a TextBody with the identical link, it will also not be tracked from the TextBody.

Metadata support

Metadata can be added to message sent using SMTP by adding an additional SMTP header. If you add an SMTP header that contains the prefix x-PM-Metadata-, it will be registered as a metadata field. For an example, here are the SMTP headers you would add to the message to register custom metadata values for color and client-id:

"x-PM-Metadata-color" : "blue"
"x-PM-Metadata-client-id" : "12345"

Troubleshooting SMTP problems

Due to the nature of the SMTP protocol it is not possible for us to return an error to the SMTP client when we find out something is wrong with the message. To work around that limitation we will log a special type of bounce – SMTPApiError. The bounce description will contain a short message containing an error description. Checking the bounce raw source will display a longer error message along with other details such as the error code. The raw source will also contain the actual SMTP message. You should monitor your bounces periodically or create a bounce webhook that will alert you if SMTP delivery failed.

Why can’t I authenticate with the SMTP server?

Please make sure you are using your server API token as both the SMTP user name and password. Also verify that you have enabled SMTP access for your server on the outbound server settings page.

Why isn’t my custom Message-ID being sent through ICOMMKT?

First, please note the difference between MessageID (which is generated by ICOMMKT and cannot be changed), and Message-ID, which is the custom value you're able to set via an SMTP header.

By default, ICOMMKT will replace all Message-ID headers for outbound SMTP messages. However, it can be useful to preserve Message-ID values for some applications that rely on them. To ensure that ICOMMKT does not replace your custom or original Message-ID header, include an additional header called X-PM-KeepID with a value of true. ICOMMKT will then pass on any original Message-ID header for the message

X-PM-KeepID : true

Troubleshooting encodings & character sets

ICOMMKT does its best to support all possible encodings, character sets, and email clients. Occasionally there are combinations of clients and character sets that will not process correctly through ICOMMKT. For instance, Mozilla Thunderbird sends ISO-8859-2 character sets using a Content-Transfer-Encoding of “8bit” which does not add a proper BOM signature. As a result, some special characters may not be processed correctly through ICOMMKT.

Common Connection Issues

Even though icomm is up and not reporting any issues on the status site, you may encounter cases where your application cannot connect to icomm. The most common causes for these issues are related to networking configuration changes that might have occurred in your environment, or done by your hosting provider without your knowledge.

What we need to confirm is:

You server(s) can lookup the IP address to connect to our API or SMTP servers.
You are able to connect to our servers from your server(s). Ports 80 or 443 for the API, and ports 25, 587, or 2525 for SMTP.

When contacting us, please provide us with the public IP(s) that your server(s) are connecting from, we will be better able to look at logs for connectivity issues on our end.

Below are the commands we ask you to run from your server(s), if you can provide the full output from these commands when contacting support, we will be much better able to assist you in sorting out connectivity issues:

API Connectivity:

First, verify that DNS is working properly:

$ nslookup api.trx.icommarketing.com

This should produce the public IP for our API. If it times out, then check and make sure you can lookup other public domains, such as example.com, yahoo.com, google.com, etc.

Next, verify that you can initiate a connection and download content from our API using the command line:

$ curl -vvv https://api.trx.icommarketing.com

It is uncommon, but if your system root certificates are out of date, curl may not be able to verify the TLS connection to the API, try the same command without TLS verification:

$ curl -vvv -k https://api.trx.icommarketing.com

If this fails, you may also attempt to connect without encryption:

$ curl -vvv http://api.trx.icommarketing.com

If you’re concerned about latency issues, then it may be useful to run 'time' first:

$ time curl -vvv https://api.trx.icommarketing.com

If all of the above items are successful, then it’s time to look at code.

SMTP Connectivity:

Similarly to the API, we want to make sure that your connections are able to resolve DNS for our SMTP servers, then we need to check connectivity.

This should produce one of our published SMTP IPs.

Next, verify that you can connect to one of the following ports: 25, 587, or 2525. NOTE: Some ISPs and hosting providers will block these ports. In other cases, they redirect this traffic to their own SMTP servers.

Attempt to open a telnet connection to each port, and send two commands by typing each and then a newline (EHLO , then QUIT), as in the example below:


    $ telnet smtp.trx.icommarketing.com
    EHLO localhost
    QUIT

The following is what a typical successful test will look like:


    telnet smtp.trx.icommarketing.com 25
    Trying 147.75.195.176...
    Connected to smtp.trx.icommarketing.com.
    Escape character is '^]'.
    220 smtp.trx.icommarketing.com ESMTP p-pm-smtp02-pktewr1
    EHLO localhost
    250-smtp.trx.icommarketing.com
    250-PIPELINING
    250-SIZE 20480000
    250-VRFY
    250-ETRN
    250-STARTTLS
    250-AUTH PLAIN LOGIN CRAM-MD5 DIGEST-MD5
    250-AUTH=PLAIN LOGIN CRAM-MD5 DIGEST-MD5
    250-ENHANCEDSTATUSCODES
    250-8BITMIME
    250 DSN
    QUIT
    221 2.0.0 Bye
    Connection closed by foreign host.

Assuming this worked as expected, you can send a simple test to yourself using a command-line tool called "swaks":

$ swaks --auth --tls -s smtp.trx.icommarketing.com--to="you@example.com"--from="your-sender-signature@example.com"--port=25

When you run the command above, will be prompted for your username and password, which are both your Server API Token.

If these items were all successful, then it’s time to look at the SMTP client code in the application.

IPs for Firewalls

Below is a list of IPs you'll want to add to your firewall for sending email through our API and SMTP.

Outbound SMTP Servers
The IP addresses that Transactional and Broadcast messages are sent from.

50.31.156.96/27 (50.31.156.96 - 127) [Transactional]
104.245.209.192/26 (104.245.209.192 - 255) [Transactional]
50.31.205.0/24 (50.31.205.1 - 255) [Broadcast]

API Access

50.31.156.109
34.192.253.140
50.31.165.246
18.216.134.80 [New]
3.137.63.180 [New]

SMTP Endpoints
The IP endpoints for accessing SMTP outbound.

CIDR Blocks / Ranges

147.75.195.176/30 [147.75.195.176 - 147.75.195.179]
147.75.202.84/30 [147.75.202.84 -147.75.202.87]
147.75.205.84/30 [147.75.205.84 - 147.75.205.87]
52.79.88.220
54.180.186.193
34.249.162.51
52.208.184.61
63.35.51.189
3.208.98.158
3.93.205.235
3.95.122.1
3.208.98.158
3.93.205.235
3.95.122.1
13.209.189.43
15.164.159.110
52.208.94.138
52.210.34.36
54.77.222.65

Inbound SMTP Servers
These IPs are where icomm's inbound MX record points.

13.58.75.120
52.36.8.247
18.221.96.15
34.211.250.229
34.211.88.250
18.221.180.145
52.210.157.196
52.213.211.243
52.51.73.41
13.125.126.102
3.34.204.228
3.34.213.247
107.22.71.110
52.2.5.255
72.44.42.226

Webhooks
These IPs apply for every webhook sent by icomm (inbound, bounce, open, etc).

3.134.147.250 (New - added 9/15/2020)
50.31.156.6
50.31.156.77
18.217.206.57

Schema Definitions

EmailBody:

Email object

From: string: The sender email address. Must have a registered and confirmed Sender Signature.
To: string: Recipient email address. Multiple addresses are comma separated.
Cc: string: Cc recipient email address. Multiple addresses are comma separated.
Bcc: string: Bcc recipient email address. Multiple addresses are comma separated.
Subject: string: Email subject.
Tag: string: Email tag that allows you to categorize outgoing emails and get detailed statistics.
HtmlBody: string: If TextBody is not specified HTML email message
TextBody: string: If HtmlBody is not specified Plain text email message.
ReplyTo: string: Reply To override email address. Defaults to the Reply To set in the sender signature.
Headers: string: List of custom headers to include.
TrackOpens: boolean: Activate open tracking for this email.
TrackLinks: string HtmlAndText, HtmlOnly, TextOnly: Activate link tracking for links in the HTML or Text bodies of this email. Possible options None HtmlAndText HtmlOnly TextOnly.
Attachments: array: List of attachments

Example

{
  "Cc": "Cc",
  "Bcc": "Bcc",
  "Headers": "",
  "TrackLinks": "HtmlAndText",
  "From": "From",
  "Attachments": "",
  "Subject": "Subject",
  "TrackOpens": true,
  "TextBody": "TextBody",
  "ReplyTo": "ReplyTo",
  "HtmlBody": "HtmlBody",
  "To": "To",
  "Tag": "Tag"
}

BatchEmail:

Email object

From: string: The sender email address. Must have a registered and confirmed Sender Signature.
To: string: Recipient email address. Multiple addresses are comma separated.
Cc: string: Cc recipient email address. Multiple addresses are comma separated.
Bcc: string: Bcc recipient email address. Multiple addresses are comma separated.
Subject: string: Email subject.
Tag: string: Email tag that allows you to categorize outgoing emails and get detailed statistics.
HtmlBody: string: If TextBody is not specified HTML email message
TextBody: string: If HtmlBody is not specified Plain text email message.
ReplyTo: string: Reply To override email address. Defaults to the Reply To set in the sender signature.
Headers: string: List of custom headers to include.
TrackOpens: boolean: Activate open tracking for this email.
TrackLinks: string HtmlAndText, HtmlOnly, TextOnly: Activate link tracking for links in the HTML or Text bodies of this email. Possible options None HtmlAndText HtmlOnly TextOnly.
Attachments: array: List of attachments

Example

{
  "Cc": "Cc",
  "Bcc": "Bcc",
  "Headers": "",
  "TrackLinks": "HtmlAndText",
  "From": "From",
  "Attachments": "",
  "Subject": "Subject",
  "TrackOpens": true,
  "TextBody": "TextBody",
  "ReplyTo": "ReplyTo",
  "HtmlBody": "HtmlBody",
  "To": "To",
  "Tag": "Tag"
}

Create_Template:

Create a template

Name: string: Name of template.
Subject: string: The content to use for the Subject when this template is used to send email. See our template language documentation for more information on the syntax for this field.
TextBody: string: The content to use for the HtmlBody when this template is used to send email. Required if TextBody is not specified. See our template language documentation for more information on the syntax for this field.
HtmlBody: string: The content to use for the TextBody when this template is used to send email. Required if HtmlBody is not specified. See our template language documentation for more information on the syntax for this field.
Alias: string: An optional string you can provide to identify this Template. Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter.

Example

{
  "TextBody": "TextBody",
  "HtmlBody": "HtmlBody",
  "Alias": "Alias",
  "Subject": "Subject",
  "Name": "Name"
}

Edit_Template:

Edit a template

Name: string: Name of template.
Subject: string: The content to use for the Subject when this template is used to send email. See our template language documentation for more information on the syntax for this field.
TextBody: string: The content to use for the HtmlBody when this template is used to send email. Required if TextBody is not specified. See our template language documentation for more information on the syntax for this field.
HtmlBody: string: The content to use for the TextBody when this template is used to send email. Required if HtmlBody is not specified. See our template language documentation for more information on the syntax for this field.
Alias: string: An optional string you can provide to identify this Template. Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter.

Example

{
  "TextBody": "TextBody",
  "HtmlBody": "HtmlBody",
  "Alias": "Alias",
  "Subject": "Subject",
  "Name": "Name"
}

Validate_Template:

Validate a template

Subject: string: The subject content to validate. Must be specified if HtmlBody or TextBody are not. See our template language documentation for more information on the syntax for this field.
TextBody: string: The html body content to validate. Must be specified if Subject or TextBody are not. See our template language documentation for more information on the syntax for this field.
HtmlBody: string: The text body content to validate. Must be specified if HtmlBody or Subject are not. See our template language documentation for more information on the syntax for this field.
TestRenderModel: string: The model to be used when rendering test content.
InlineCssForHtmlTestRender: string: When HtmlBody is specified, the test render will have style blocks inlined as style attributes on matching html elements. You may disable the css inlining behavior by passing false for this parameter.

Example

{
  "TextBody": "TextBody",
  "TestRenderModel": "TestRenderModel",
  "HtmlBody": "HtmlBody",
  "InlineCssForHtmlTestRender": "InlineCssForHtmlTestRender",
  "Subject": "Subject"
}

Send_Templated_Email:

Send email with template

TemplateId: integer: The template to use when sending this message. Required if TemplateAlias is not specified.
TemplateAlias: string: The alias of a template to use when sending this message. Required if TemplateID is not specified.
TemplateModel: object: The model to be applied to the specified template to generate HtmlBody, TextBody, and Subject.
InlineCss: boolean: By default, if the specified template contains an HTMLBody, we will apply the style blocks as inline attributes to the rendered HTML content. You may opt-out of this behavior by passing false for this request field.
From: string: The sender email address. Must have a registered and confirmed Sender Signature.
To: string: Recipient email address. Multiple addresses are comma separated. Max 50.
Cc: string: Cc recipient email address. Multiple addresses are comma separated. Max 50.
Bcc: string: Bcc recipient email address. Multiple addresses are comma separated. Max 50.
Tag: string: Email tag that allows you to categorize outgoing emails and get detailed statistics.
ReplyTo: string: Reply To override email address. Defaults to the Reply To set in the sender signature.
Headers: string: List of custom headers to include.
TrackOpens: string: Activate open tracking for this email.
TrackLinks: string: Activate link tracking for links in the HTML or Text bodies of this email. Possible (None, HtmlAndText, HtmlOnly, TextOnly)
Attachments: array: List of attachments.

Example

{
  "TemplateId": 1234,
  "TemplateModel": {
    "user_name": "John Smith",
    "company": {
      "name": "ACME"
    }
  },
  "InlineCss": true,
  "From": "sender@example.com",
  "To": "receiver@example.com",
  "Cc": "copied@example.com",
  "Bcc": "blank-copied@example.com",
  "Tag": "Invitation",
  "ReplyTo": "reply@example.com",
  "Headers": [
    {
      "Name": "CUSTOM-HEADER",
      "Value": "value"
    }
  ],
  "TrackOpens": true,
  "TrackLinks": "None",
  "Attachments": [
    {
      "Name": "readme.txt",
      "Content": "dGVzdCBjb250ZW50",
      "ContentType": "text/plain"
    },
    {
      "Name": "report.pdf",
      "Content": "dGVzdCBjb250ZW50",
      "ContentType": "application/octet-stream"
    }
  ],
  "Metadata": {
      "color":"blue",
      "client-id":"12345"
   }
}

Send_Batch_Templated_Email:

Send batch with templates

TemplateAlias: string: The template to use for this message. This value is required if TemplateID is not supplied. If both are supplied, TemplateID will be used to select the template.
TemplateId: integer: The template to use for this message. This value is required if TemplateAlias is not supplied. If both are supplied, TemplateID will be used to select the template.
From: string: The sender email address. Must have a registered and confirmed Sender Signature.
To: string: Recipient email address. Multiple addresses are comma separated. Max 50.
Cc: string: Cc recipient email address. Multiple addresses are comma separated. Max 50.
Bcc: string: Bcc recipient email address. Multiple addresses are comma separated. Max 50.
Tag: string: Email tag that allows you to categorize outgoing emails and get detailed statistics.
ReplyTo: string: Reply To override email address. Defaults to the Reply To set in the sender signature.
Headers: string: List of custom headers to include.
TrackOpens: string: Activate open tracking for this email.
TrackLinks: string: Activate link tracking for links in the HTML or Text bodies of this email. Possible (None, HtmlAndText, HtmlOnly,TextOnly)
Attachments: array: List of attachments.

Example

{
  "Cc": "Cc",
  "ReplyTo": "ReplyTo",
  "Bcc": "Bcc",
  "Headers": "Headers",
  "TrackLinks": "TrackLinks",
  "From": "From",
  "To": "To",
  "Tag": "Tag",
  "Attachments": "",
  "TemplateId": 0,
  "TemplateAlias": "TemplateAlias",
  "TrackOpens": "TrackOpens"
}

Suppressions:

Suppressions Array

EmailAddress: string: Related Email Address.

Example

[{
  "EmailAddress": "test@test.com",  
}]

Create_Trigger_For_Tag:

Create a trigger for a tag

MatchName: string: Name of the tag that will activate this trigger.
TrackOpens: boolean: Indicates if this trigger activates open tracking.

Example

{
  "MatchName": "MatchName",
  "TrackOpens": true
}

Edit_Single_Trigger:

Edit a single trigger

MatchName: string: Name of the tag that will activate this trigger.
TrackOpens: boolean: Indicates if this trigger activates open tracking.

Example

{
  "MatchName": "MatchName",
  "TrackOpens": true
}

CreateInboundRuleTrigger:

Create an inbound rule trigger

Rule: string: Email address (or domain) that you would like to block from sending.

Example

{
  "Rule": "Rule"
}

Template Syntax:

ICOMMKT Template Syntax

ICOMMKT Templates use a very simple, yet very powerful, language called Mustachio. Mustachio has its roots with Mustache, but includes a few advanced features that make it great for authoring plain text and html emails.

Here's everything you need to know about the language.

Variable Interpolation:

"Variable Interpolation" is the heart and soul of any templating language.

If you have a template model like this (represented as JSON):

{
        "person" : { 
            "first_name" : "Andrew",
        }
}

And this template:

Hello {{ person.first_name }}

Mustachio will produce this content when you combine the two:

Hello Andrew

If you've used Mustache.js, this should be very familiar. But Mustachio has a few more capabilities that make writing templates a breeze.

Scoping:

Sometimes we'll have more complex models, and so scoping to a particular property will make the markup easier to read:

{{#person}}
   Hello {{first_name}} 
{{/person}}

Notice that if we're building a section of the template that uses multiple properties from "person", we don't need to keep repeating "person." with each variable interpolation.

Collection Handling:

Let's say we have this more complicated model:

{
    "company_name" : "ACME Rockets, Inc.",
    "employees" : [
         { "name" : "Wile E. Coyote"},
         { "name" : "Road Runner"}
    ]
}

And this template:

{{ company_name }} Employees:
<ul>
{{#each employees}}
	<li>{{ name }}</li>
{{/each}}
</ul>

Mustachio will combine these and produce the following HTML:

ACME Rockets, Inc. Employees
<ul>
	<li>Wile E. Coyote</li>
	<li>Road Runner</li>
</ul>

Advanced Interpolation:

If we've scoped our template to a property of a model, we may want to "reach up" to a property in the outer scope. For example, let's say we wanted to change the content from the Collection Handling example above to look like this:

<ul>
	<li>Wile E. Coyote works for: ACME Rockets, Inc.</li>
	<li>Road Runner works for: ACME Rockets, Inc.</li>
</ul>

We can use a special interpolation syntax to do this without needing to repeat the values in our template model:

<ul>
{{each employees}}
  <li>{{name}} works for: {{../company_name}}</li>
{{/each}}
</ul>

Note the ../ in the template, which just means "go up one level" in my template model and look for the property name that follows. You can go up as many levels in your model as needed by including ../ multiple times at the start of your {{ ... }} section.

Advanced Value Handling:

Mustachio is permissive about missing values in your models. If you scope to a property that does not exist, Mustachio will skip that section. In this way, you can build templates that do not require if/else logic.

To show this, let's use the following model:

{
    "company_name" : "ACME Rockets, Inc.",
    "employees" : [
     { "name" : "Wile E. Coyote", "position" : "Quality Assurance Tester"},
     { "name" : "Road Runner"}
    ]
}

And we update the template:

<ul>
    {{#each employees}}
        <li>
            {{name}} works for: {{../../company_name}}
            {{#position}}as a {{.}}{{/position}}
        </li>
    {{/each}}
</ul>

When we use Mustachio we will produce the following HTML:

<ul>
    <li>Wile E. Coyote works for: ACME Rockets, Inc. as a Quality Assurance Tester</li>
    <li>Road Runner works for: ACME Rockets, Inc.</li>
</ul>

Note that because Road Runner doesn't have a 'position' property, " as a..." is omitted from the output. Also note that we can use . in the Variable Interpolation to reference the model object in the {{#position}} scoped block.

Inverted Groups (or, how to make Placeholders):

Mustachio will skip anything in a template that reference a value that is null, false, or empty (such as an array that has no elements). However, sometimes it's useful to include content specifically when a value is absent from the model, and, of course, Mustachio supports this using "Inverted Groups":

<ul>
{{#each employees}}
    <li>
        {{name}} works for: {{../../company_name}}
        {{#position}} as a {{.}}{{/position}}
        {{^ years_employed}}since who knows when?{{/years_employed}}
    </li>
{{/each}}
</ul>

In the above example, if years_employed is not specified in our template model, and so therefore, since who knows when? will be rendered.

Inverted Groups are a powerful way to provide placeholder text when information is not available, or not applicable.

Content Safety:

Normally, the information you want to include in a template will be simple scalar values, these values typically lack html markup, and are safe to render to browsers as-is. However, if you accept content from untrusted sources that you wish to embed, it's possible that this content could contain unsafe values that could lead to issues when rendered and served in a browser. This is a common "cross-site scripting" attack, and Mustachio is safe by default:

Let's take this model:

{
   "user_submitted_content" : "<script>$.sendUserPasswordToUntrustedWebsite();</script>"
}

And this template:

<div class="user_comment">{{user_submitted_content}}</div>

Mustachio automatically HTML encodes the values that it interpolates, so that, while producing "ugly" content, the output is rendered harmless:

<div class="user_comment"><script>$.sendUserPasswordToUntrustedWebsite();</script></div>

If you need to opt-out of this behavior, Mustachio provides two syntaxes to accomplish this:

{{{ user_submitted_content }}}

and

{{& user_submitted_content }}

Remember that not escaping content creates a security risk if you'll be presenting the template's output in a browser.

Last updated February 12th, 2018

Documentation by Spectacle