Message archive integration guide¶
This guide will explain the basics of the Message archive solution from Marigold Engage .
Message archive
Message archiving offers access to the full communication history, towards each contact.
The integration steps are explained as follows:
- Request access token
- Send a messages
- Query sent messages for a recipient
- Preview the content of the message
- Download the content of the message
API playground - Postman
To facilitate playing around with the EDC API, you can download a ready-to-use Postman collection to kick-start using the API.
1. Request access token¶
For security and identification, it is needed to request an access token using either a client-side or a server-side OAuth 2.0 implementation.
Oauth Access token
More information on how to authenticate can be found in our guide about Oauth Access token
After authenticating using the Oauth2 flow, the returned access_token can be used when making API calls towards Marigold Engage Delivery Cloud.
The access token is a temporary token that will expire after a certain period. Most modern Oauth2.0 clients support automatic refreshing of the access token and handling the authentication process.
2. Send messages¶
There are two ways to send messages:
- Using the Marigold Engage Delivery Cloud API
- Using Marigold Engage or Campaign
Send messages via API¶
In the "send email messages" guide, we explain more in detail how to use the Marigold Engage Delivery Cloud API to send messages. For the message archive guide, we will reuse the example from the "send email messages" guide.
Request body example for an email message:
[
{
"reference": "2a0a0b3c547296",
"content": {
"html": "<!DOCTYPE html>\r\n<html lang=\"en\" xmlns=\"http:\/\/www.w3.org\/1999\/xhtml\" xmlns:v=\"urn:schemas-microsoft-com:vml\" xmlns:o=\"urn:schemas-microsoft-com:office:office\">\r\n<body>\r\n<table style=\"border: 1px solid gray; width: 600px;\" cellspacing=\"0\" border=\"0\">\r\n <tr>\r\n <td align=\"center\" style=\"padding: 1em 2.5em; text-align: center; font-family: 'Montserrat', sans-serif; font-size: 20px; font-weight: 700; text-transform: uppercase;\">\r\n RestoBar\r\n <\/td>\r\n <\/tr>\r\n <tr>\r\n <td >\r\n <img src=\"https:\/\/developers.slgnt.eu\/assets\/guides\/html_email_cta_1.png\" alt=\"\" width=\"600\" height=\"400\" border=\"0\" style=\"margin: auto; display: block;\"\/>\r\n <\/td>\r\n <\/tr>\r\n<\/table>\r\n<\/body>\r\n<\/html>",
"text": "We Serve Healthy & Delicious Foods, Get Your Order Here!"
},
"headers": {
"subject": "RestoBar - Order Now!",
"to": {
"alias": "Jane Doe",
"address": "jane.doe@example.com"
},
"from": {
"alias": "RestoBar",
"address": "restobar@example.com"
},
"reply": {
"alias": "RestoBar",
"address": "restobar@example.com"
},
"list_unsubscribe": "<https://www.example.com/unsubscribe.aspx?ID=123456>, <mailto:unsubscribe@example.com?subject=unsubscribe 123456>"
},
"context": {
"profile": "crm-id-123456789",
"tags": [
"resto-order-now-campaign-spring"
],
"metadata": "{\"name\":\"jane.doe\",\"ref\":123456789}"
}
}
]
profile
The profile field is important, as it is used to track the recipient in the message archive & reporting.
Without going into the details of all fields, take note of the profile field, since we need this reference when querying the message archive.
Send messages via Marigold Engage /Campaign¶
Messages being sent via Engageor Campaign will use the EDC engine behind the scenes. All the message information will be automatically provided by SMC/Campaign and passed to EDC.
profile
The profile reference generated by SMC/Campaign, will be a combination of the Marigold Engage LIST ID + USER ID with an "." as the separator.
Example: 123.123456 where "123" is the LIST ID and "123456" is the USER ID.
message reference
The message reference generated by SMC/Campaign, will be a combination of the Marigold Engage SLOT ID + ACTION IN QUEUE ID with an "_" as the separator. It is a unique reference for each send message.
Example: ABCD39B2-6031-4427-A5E8-172D6E20B61B_98765 where "ABCD..." is the SLOT ID and "98765" is the ACTION IN QUEUE ID.
context tags
The tags generated by SMC/Campaign, will contain a campaign reference which is a combination of "CPG" prefix, with the "tenant name" and CAMPAIGN ID with an "_" as the separator.
Example: CPG_EU.ACME_45678 where "CPG" is the prefix, "EU.ACME" represents the tenant name and "45678" is the campaign reference.
3. Query sent messages for a recipient¶
The sending of messages is an operational process, meaning that the content and the message details are passed along between systems in an automated manner. For several reasons, it can be relevant to see the generated message that was sent towards a specific recipient.
By using the "message archive" from Marigold Engage , it is possible to retrieve the messages that were sent out and download/display them for each profile.
By using the message archive API, it is possible to query the full archive of messages that were sent out. The archive can be searched from the perspective of a profile (which represents a reference towards a contact or recipient).
API documentation
All the response properties are documented in detail in the API documentation.
An example, where you want to query all the messages that you have sent to profile "Jane Doe" with profileId "crm-id-123456789".
which will return a list of messages that were sent to the specific recipient.
{
"value": [
{
"message_id": "2a0a0b3c547296",
"channel": "email",
"tags": [
"resto-order-now-campaign-spring"
],
"profile": "crm-id-123456789",
"subject": "RestoBar - Order Now!",
"metadata": "{\"name\":\"jane.doe\",\"ref\":123456789}",
"timestamp": "2022-02-18T13:57:49.224633Z"
},
{
"message_id": "674d25d",
"channel": "email",
"tags": [
"singlesday-summer"
],
"profile": "9981.1",
"metadata": "{\"mid\":\"6025\",\"cid\":\"0\",\"lid\":\"9981\",\"aiq\":\"92233829321154\",\"uid\":\"1\",\"aid\":\"0\"}",
"attachments": [
{
"file_name": "message_attachment.pdf",
"mime_type": "application/pdf"
}
],
"subject": "Singles day restaurant voucher",
"timestamp": "2021-03-18T11:25:00.123Z"
}
]
}
This list returns relevant metadata like when the message was sent, towards which channel, ...
messageId
The message_id field is important, as it is used to reference 1 specific message for a recipient.
For messages send via SMC/Campaign, this messageId will be a combination of the Marigold Engage SLOT ID + ACTION IN QUEUE ID with an "_" as the separator.
From the results of all matching messages, you want to review the content of a specific message. By using the message_id you can request the full content of the delivered message.
metadata
The metadata field may contain information that is passed along to EDC. This information is purely metadata, and it won't be interpreted by EDC. There is no specific format required for this field.
For messages sent via SMC/Campaign, this metadata will contain a number of SMC/Campaign related fields, serialized in a JSON format:
mid: the Marigold Engage MESSAGE ID of the mail objectcid: the Marigold Engage CAMPAIGN ID of the campaign objectlid: the Marigold Engage LIST ID of the userlist objectaiq: the Marigold Engage ACTION IN QUEUE ID of the unique e-mail towards a customer from the ACTIONINQUEUE table (also used in ACTIONQUEUE and FLAGS) - unique for a user (list+userid), campaign, action, iteration (same email sent has a different AIQ ID)uid: the Marigold Engage USER ID of the user object in the userlistaid: the Marigold Engage ACTION ID of the component node of an outbound communication in a journey (Campaign database)
4. Preview the content of the message as HTML or PDF¶
By passing on the message_id to the "preview" endpoint, you can request a preview of the message content as HTML or PDF.
The response for an email message is the content in HTML format to be displayed in the browser. For mobile & SMS messages, you get to see the full message on a mobile device.
Example of the preview response for an email message:
<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
<body>
<table style="border: 1px solid gray; width: 600px;" cellspacing="0" border="0">
<tr>
<td align="center" style="padding: 1em 2.5em; text-align: center; font-family: 'Montserrat', sans-serif; font-size: 20px; font-weight: 700; text-transform: uppercase;">
RestoBar
</td>
</tr>
<tr>
<td >
<img src="https://getstarted.slgnt.io/engage/assets/guides/html_email_cta_1.png" alt="" width="600" height="400" border="0" style="margin: auto; display: block;"/>
</td>
</tr>
</table>
</body>
</html>
By passing on the message_id to the "preview" endpoint with the Accept header application/pdf, you can request a preview of the message content as a PDF file.
5. Download the content of the message¶
By passing on the message_id to the "download" endpoint, you can request a download of the message content.
The response for an email message is the content in EML format, which can be opened by an email client (like outlook) or used programmatically to be displayed in your internal application or transformed into a PDF. For mobile & SMS messages, you get the full message in JSON format.
When email message contained attachments, the attachments are embedded in the downloaded EML file.