How can we help?

How are Message IDs created, defined and used?

All messages created and sent via the Cordial platform are given IDs. The structure and format of the ID is dependent on the type of message, how it was sent and to whom it was sent.

This article will go over the following message IDs:

  • Message ID (msID) - Identifies a sent or draft batch message as well as a sent automated (aggregated daily or hourly) messages.
  • Automation Template ID (mdtID) - Identifies a published or draft automation template.
  • Message Contact ID (mcID) - Identifies a specific message sent to a specific contact at a specific time.

Message ID (msID)

The message ID references both batch messages and automated message (aggregated daily or hourly) sends in the UI and the API.

Note: msID and bmID (batch message ID) are synonymous in most use cases. For the purposes of this article, we'll refer to message ID as msID.

msID in Batch Messages

Batch messages are sent to an audience of contacts in a single "batch" send, therefore all messages in a batch send are referenced by the same message ID.

When a batch message is created, it is immediately assigned an msID, which makes it possible for an msID to reference either a draft or sent batch message.

The msID may be rendered in a message using Smarty system variables

Note: When a batch message is deployed, each individual message sent to a contact is identified with a message contact ID (mcID)

The msID is a concatenation of 3 system values that describes which account sent the message, which message was sent, as well as the message type.

Example msID for a batch message:

264:590261c7f0c360ee35a8046f:ot

The msID is made of 3 parts:

  1. Account ID
  2. Database ID for the message
  3. Type of message
    • ot = one time

msID in Automated Messages

The message ID (msID) is used to identify sent recurring, API and event triggered automated messages.

Note: Automation templates are identified using the message delivery template ID (mdtID).

Recurring Messages

When automations are sent as recurring messages, they are sent to an audience of contacts at a specified recurring interval. Each time a batch of recurring message is sent, it is assigned an msID.

Example msID for a recurring automated message:

264:590261c7f0c360ee35a8046f:rm201710121700

The msID is made of 4 parts:

  1. Account ID
  2. Database ID for the message
  3. Type of message
    • rm = recurring message
  4. Recurring message timestamp
    • YYYY = year (2017)
    • MM = month (10)
    • DD = day (12)
    • HH = hour (17)
    • mm = minutes (00)

API and Event Triggered Automated Messages

API and event triggered automated messages are sent on a one to one basis. These automations may send for long periods of time (e.g. order confirmations, welcome messages, etc.) and frequently deploy in relatively high volumes. In order to reduce the number of unique ID's that are generated by automated messages, Cordial aggregates daily automated message sends (or hourly - depending on configuration) under a single message ID.

Example msID for an API or event triggered automated message:

252:6acf7ca0089974e1f21a5683b9266b19:d171221

The msID is made of 3 parts:

  1. Account ID
  2. Database ID for the message
  3. Message send aggregate date
    • d = daily aggregate
    • YY = year (2017)
    • MM = month (12)
    • DD = day (21)

Viewing the msID in the UI

Batch Messages

The msID can be viewed in the UI for batch messages by navigating to a draft or sent batch message and noting the URL. The highlighted area in the image below shows the msID within the URL of a batch message page.

Automated Messages

When viewing an automated message in the UI, only the mdtID is available via the URL. However, it is possible to paste an msID (obtained via a GET /batchmessages API call) into the URL of a batch message page to get stats on a sent automated message (aggregated daily or hourly).

Viewing the msID in the API

Batch Messages

Batch messages are referenced in the API using the msID and the batch messages API calls.

For example, when performing a GET /batchmessages API call, you'll find the msID returned in the response. The msID is highlighted in the image below (from the Swagger API tool).

Note: In API responses, bmID is used as the key for message ID.

The message ID is also used to reference messages in contact activities and contact activity export API calls.

Automated Messages

Aggregated daily (or hourly) automated message sends are referenced in the API using the msID and the batch messages API calls.

For example, when performing a GET /batchmessages API call, you'll find the msID returned in the response. The msID is highlighted in the image below (from the Swagger API tool)

Note: In API responses, bmID is used as the key for message ID.

Message Delivery Template ID (mdtID)

The message delivery template ID (mdtID) represents both the published and draft versions of an Automation template.

Example mdtID:

591f1a26ac0c811781bf44ea

The mdtID can be used to reference the total aggregate stats of an automation template using the automations templates API calls.

Note that when an automation is sent, it's stats are also aggregated daily (or hourly) and referenced using a message ID (msID).

Viewing the mdtID in the UI

The mdtID can be viewed in the UI for automation templates by navigating to the automation template and noting the URL. The highlighted area in the image below shows the mdtID within the URL of an automated template page.

Viewing the mdtID in the API

Automation templates are referenced in the API using the automation key and the automations templates API calls.

The mdtID is returned when performing a GET /automationtemplates API call.

For example, when performing a GET /automationtemplates API call, you'll find the mdtID returned in the response. The mdtID is highlighted in the image below (from the Swagger API tool).

Message Contact ID (mcID)

Individual messages sent through Cordial are given a unique message contact ID.

The message contact ID (mcID) is a concatenation of several system values that describes which account sent the message, which message was sent, which contact the message was sent to, and the message type.

The mcID may be rendered in a message using Smarty system variables

Example mcID:

264:590261c7f0c360ee35a8046f:ot:5900ddf2ac0c81178189d93b:1

The mcID is made of 3 main parts:

  1. msID (Message ID)
    msID is made of 3 parts:
    1. Account ID
    2. Database ID for the message
    3. Type of message
      • ot = one time
      • rm = recurring message
  2. cID (Contact ID)
  3. Unique timestamp - used to make the mcID unique in the event a contact is sent the same automation template within the same day (or hour).

Viewing the mcID in the API

Message events (sent, open, click, etc.) are referenced in the API using the contact activities API calls.

For example, when performing a GET /contactactivities API call, you'll find the mcID returned in the response for message specific events. The mcID is highlighted in the image below (from the Swagger API tool).

Comments

0 comments

Please sign in to leave a comment.