Messaging Connector

Page Contents

Staging a campaign#
Editing a campaign#
Testing a campaign#
Publishing a campaign#
Objects#
Stage Block Group Object#
Edit Block Group Object#
Stage Message Object#
Edit Message Object#
Variant Object#
Variant Field Object#

Coming soon! Available from version 25.5. Access to the Messaging Connector includes access to the Message API. The API allows you to create, edit, test and publish campaigns. Contact your Client Manager for information on pricing and access.

Staging a campaign

Creating a new campaign. This operation will fail if the campaign already exists.

Request

POST /messages/v1/campaign/email/:stage

{
  "name": "",
  "flowTemplate": "",
  "senderName": "",
  "senderEmail": "",
  "replyToEmail": "",
  "subject": "",
  "schedule": "",
  "templateName": "",
  "targetGroupName": "",
  "limitToTargetGroupName": "",
  "utmCampaign": "",
  "blockGroups": []
}

Example

{
  "name": "newsletter-001",
  "flowTemplate": "NewsletterFlowTemplate",
  "senderName": "Cafe Connect",
  "senderEmail": "newsletter@coffee.agilliclabs.com",
  "replyToEmail": "newsletter@coffee.agilliclabs.com",
  "subject": "Newsletter 001 <globaldata>YEAR</globaldata>",
  "schedule": "2025-12-01 12:00:00",
  "templateName": "newsletter.html",
  "targetGroupName": "Roastery Newsletter",
  "limitToTargetGroupName": "Valid Newsletter",
  "utmCampaign": "newsletter-roastery",
  "blockGroups": [
    {
      "blockGroupId": "message_group",
      "messages": [
        {
          "name": "Roastery News 001",
          "maxVariants": 1,
          "collapsed": false,
          "messageTemplate": "RoasteryMessageTemplate",
          "blockId": "message-side_article",
          "variants": [
            {
              "name": "Fallback",
              "targetGroupName": "All recipients",
              "fields": {
                "hero-image":"",
                "message-trompet":"",
                "message-header":"",
                "message-content":"",
                "cta-link":""
              }
            },
            {
              "name": "Gold Loyalty",
              "targetGroupName": "Gold Loyalty",
              "fields": {
                "hero-image":"",
                "message-trompet":"",
                "message-header":"",
                "message-content":"",
                "cta-link":""
              }
            },
            {
              "name": "Silver Loyalty",
              "targetGroupName": "Silver Loyalty",
              "fields": {
                "hero-image":"",
                "message-trompet":"",
                "message-header":"",
                "message-content":"",
                "cta-link":""
              }
            }
          ]
        }
      ]
    }
  ]
}

Properties

Name	Required	Type	Description
`name`	Yes	String	Name of the campaign. Will be used as the Flow and Email name.
`flowTemplate`	No	String	The name of the flow template.
`sendername`	No	String	The from name of the email – also know. as “Personal from”.
`senderEmail`	No	String	The email from address.
`replyToEmail`	No	String	The email reply-to address.
`subject`	Yes	String	The email subject line.
`schedule`	No	String	The flow schedule. Date format must match what is defined in Settings / API.
`templateName`	Yes	String	The name of the email HTML template.
`targetGroupName`	Yes	String	The name of the target group to be used on the campaign flow.
`limitToTargetGroupName`	No	String	The name of the global target group to be used on the campaign flow.
`utmCampaign`	No	String	The utm_campaign to be set on the email. Will default to the name of email if omitted.
`blockGroups`	Yes	Block Group object	Definition

Response

{
  "success": true,
  "message": "",
  "data": {
    "campaignId": "",
    "campaignName": "",
    "schedule": ""
  }
}

Editing a campaign

Editing a campaign. This operation will fail if the campaign does not exist.

Please note that the amount of “variants” is expected to remain the same between a :stage and :edit request.

Request

POST /messages/v1/campaign/email/:edit

{
  "campaignId": "",
  "senderName": "",
  "senderEmail": "",
  "replyToEmail": "",
  "subject": "",
  "schedule": "",
  "targetGroupName": "",
  "limitToTargetGroupName": "",
  "utmCampaign": "",
  "blockGroups": []
}

Example

{
  "campaignId": "#BaaB",
  "senderName": "Cafe Connect",
  "senderEmail": "newsletter@coffee.agilliclabs.com",
  "replyToEmail": "newsletter@coffee.agilliclabs.com",
  "subject": "Newsletter 001 <globaldata>YEAR</globaldata>",
  "schedule": "2025-12-01 12:00:00",
  "targetGroupName": "Roastery Newsletter",
  "limitToTargetGroupName": "Valid Newsletter",
  "utmCampaign": "newsletter-roastery",
  "blockGroups": [
    {
      "messages": [
        {
          "name": "Roastery News 001",
          "maxVariants": 1,
          "collapsed": true,
          "variants": [
            {
              "name": "Fallback",
              "targetGroupName": "All recipients",
              "fields": {
                "hero-image":"",
                "message-trompet":"",
                "message-header":"",
                "message-content":"",
                "cta-link":""
              }
            },
            {
              "name": "Gold Loyalty",
              "targetGroupName": "Gold Loyalty",
              "fields": {
                "hero-image":"",
                "message-trompet":"",
                "message-header":"",
                "message-content":"",
                "cta-link":""
              }
            },
            {
              "name": "Silver Loyalty",
              "targetGroupName": "Silver Loyalty",
              "fields": {
                "hero-image":"",
                "message-trompet":"",
                "message-header":"",
                "message-content":"",
                "cta-link":""
              }
            }
          ]
        }
      ]
    }
  ]
}

Properties

Name	Required	Type	Description
`campaignId`	Yes	String	Campaign identifier
`sendername`	No	String	The from name of the email – also know. as “Personal from”.
`senderEmail`	No	String	The email from address.
`replyToEmail`	No	String	The email reply-to address.
`subject`	Yes	String	The email subject line.
`schedule`	No	String	The flow schedule. Date format must match what is defined in Settings / API.
`targetGroupName`	Yes	String	The name of the target group to be used on the campaign flow.
`limitToTargetGroupName`	No	String	The name of the global target group to be used on the campaign flow.
`utmCampaign`	No	String	The utm_campaign to be set on the email. Will default to the name of email if omitted.
`blockGroups`	Yes	Block Group object	Definition

Response

{
  "success": true,
  "message": "",
  "data": {
    "campaignId": "",
    "campaignName": "",
    "schedule": ""
  }
}

Testing a campaign

Testing a campaign. This operation will fail if the campaign does not exist.

Request

POST /messages/v1/campaign/email/:test

{
  "campaignId": "",
  "viewAsRecipientId": "",
  "sendMessage": ""
}

Properties

Name	Required	Type	Description
`campaignId`	Yes	String	Campaign identifier
`viewAsRecipientId`	Yes	String	Recipient Identifier value of the recipient to test with
`sendMessage`	No	String	Allowed values are `true/false`. Controls whether a message should be sent to the `viewAsRecipientId` value.

Response

{
  "success": true,
  "message": "",
  "data": {
    "subject": "",
    "content": ""
  }
}

Publishing a campaign

Coming later. Subject to change.

Publishing a campaign. This operation will fail if the campaign does not exist.

Request

POST /messages/v1/campaign/email/:publish

{
  "campaignId": ""
}

Properties

Name	Required	Type	Description
`campaignId`	Yes	String	Campaign identifier

Objects

Stage Block Group Object

{
  "blockGroupId": "",
  "messages": []
}

Properties

Name	Required	Type	Description
`blockGroupId`	Yes	String	Name of the blockgroup id (agid in HTML template).
`messages`	Yes	Array of Message objects	Definition

Edit Block Group Object

{
  "messages": []
}

Properties

Name	Required	Type	Description
`messages`	Yes	Array of Message objects	Definition

Stage Message Object

{
  "name": "",
  "maxVariants": 1,
  "collapsed": false,
  "messageTemplate": "",
  "blockId": "",
  "variants": []
}

Properties

Name	Required	Type	Description
`name`	Yes	String	Name of the message (promotion).
`maxVariants`	No	Integer	Max variants (propositions) to show setting.
`collapsed`	No	Boolean	Allowed values are `true/false`. Hide the block if the recipient does not match any propositions.
`messageTemplate`	Yes	String	Name of the message (promotion) template.
`blockId`	Yes	String	Name of the block id (agid in HTML template).
`variants`	Yes	Array of Variant objects	Definition

Edit Message Object

{
  "name": "",
  "maxVariants": 1,
  "variants": []
}

Properties

Name	Required	Type	Description
`name`	Yes	String	Name of the message (promotion).
`maxVariants`	No	Integer	Max variants (propositions) to show setting.
`collapsed`	No	Boolean	Allowed values are true/false. Hide the block if the recipient does not match any propositions.
`variants`	Yes	Array of Variant objects	Definition

Variant Object

{
  "name": "",
  "targetGroupName": "",
  "fields": {}
}

Properties

Name	Required	Type	Description
`name`	Yes	String	Name of the message (promotion).
`targetGroupName`	No	String	Name of the target group to be used as a condition.
`fields`	Yes	Array of Variant Field objects	Definition

Variant Field Object

{
  "(insert the variant field name here)": "value",
}

Properties

Name	Required	Type	Description
Must match a promotion field name in the found in the requested messageTemplate	Yes	String	Name of the message field (promotion field).

Examples

Promotion field of the type “plain”.

{
  "message-trompet": "Latest news"
}

Promotion field of the type “rich”.

{
  "message-content": "Get ready to carve jack o lanterns with our newest offering - <b>Pumpkin Spice Cold Foam Shaken Macchiato!</b>
Find it in a store near you."
}

Promotion field of the type “link”. Create or add existing events by appending ?evt=

{
  "message-link": "https://coffee.agilliclabs.com?evt=clicked_article"
}

Promotion field of the type “image”. Value must be an absolute URL to an image resource.

{
  "message-image": "https://coffee.agilliccdn.com/pi7g7w/MjAyMTEy/Mjc=/NTcyMTE4MmItZWZmNi00ZGViLTk5MzAtZDIzYmFiZDI1Y2Y1.png"
}

Full example

{
  "message-trompet": "Latest news",
  "message-header": "It's spooky season!",
  "message-content": "Get ready to carve jack o lanterns with our newest offering - Pumpkin Spice Cold Foam Shaken Macchiato!
Find it in a store near you.", 
  "message-link": "https://coffee.agilliclabs.com?evt=clicked_article",
  "message-image": "https://coffee.agilliccdn.com/pi7g7w/MjAyMTEy/Mjc=/NTcyMTE4MmItZWZmNi00ZGViLTk5MzAtZDIzYmFiZDI1Y2Y1.png"
}

Staging a campaign#

Editing a campaign#

Testing a campaign#

Publishing a campaign#

Objects#

Stage Block Group Object#

Edit Block Group Object#

Stage Message Object#

Edit Message Object#

Variant Object#

Variant Field Object#

Staging a campaign

Editing a campaign

Testing a campaign

Publishing a campaign

Objects

Stage Block Group Object

Edit Block Group Object

Stage Message Object

Edit Message Object

Variant Object

Variant Field Object