Sending messages

In order to send an Email message, you must have an active Email channel and perform a HTTP request to the following endpoint with a valid access key

Send a message

Send a message to a channel

POST/workspaces/{workspaceId}/channels/{channelId}/messages

Authorization

useraccessKey

Path parameters

workspaceId*string (uuid)

The ID of the workspace

channelId*string (uuid)

The ID for a channel

Body

application/json

senderSender (object)

receiver*Receiver (object)

referenceReference (string)

templatenullable Template (object)

metaMeta (object)

replyToReplyTo (object)

bodyMessageBody

capFrequencyboolean

If set to true, the frequency capping settings of the platform will be used to either allow or reject the message to a contact. Can only be set to true if the message is sent to a contact and .meta.extraInformation.useCase is marketing.

one of

ChannelMessageCreateWithTemplateChannelMessageCreateWithBody

Response

202400404409422

Message was accepted for processing

Body

application/json

id*Id-2 (string (uuid))

channelId*ChannelId (string (uuid))

sender*one of

ChannelConnectorChannelContact

receiver*one of

ChannelConnectorChannelContacts

metaMeta (object)

referenceReference (string)

partsParts (array of object)

status*Status-3 (enum)

acceptedprocessingsentsending_faileddelivereddelivery_faileddeleted

reasonstring

directionDirection (enum)

incomingoutgoing

replyToReplyTo (object)

lastStatusAt*string (date-time)

createdAt*string (date-time)

updatedAt*string (date-time)

detailsstring

This field is used to store additional information related to the message status.

failurenullable Failure (object)

any of

objectobject

Request

JavaScriptCurl

const response = await fetch('/workspaces/{workspaceId}/channels/{channelId}/messages', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "receiver": {
        "contacts": [
          {}
        ]
      }
    }),
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "channelId": "123e4567-e89b-12d3-a456-426614174000",
  "sender": {
    "connector": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "annotations": {
        "name": "text"
      }
    }
  },
  "receiver": {
    "connector": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "annotations": {
        "name": "text"
      }
    }
  },
  "meta": {
    "referral": {
      "source": "text",
      "title": "text",
      "text": "text",
      "group": "text",
      "metadata": {
        "source_id": "text",
        "source_url": "text",
        "media_url": "text",
        "tracking_id": "text"
      }
    },
    "order": {
      "products": [
        {
          "externalCatalogId": "text",
          "externalProductId": "text",
          "price": {
            "currencyCode": "text"
          }
        }
      ]
    },
    "referredProduct": {
      "externalCatalogId": "text",
      "externalProductId": "text"
    },
    "email": {
      "subject": "text"
    }
  },
  "reference": "text",
  "parts": [
    {
      "platformReference": "text"
    }
  ],
  "status": "accepted",
  "reason": "text",
  "direction": "incoming",
  "replyTo": {
    "id": "text",
    "type": "message"
  },
  "lastStatusAt": "2024-04-29T11:00:56.066Z",
  "createdAt": "2024-04-29T11:00:56.066Z",
  "updatedAt": "2024-04-29T11:00:56.066Z",
  "details": "text",
  "failure": {
    "source": {
      "code": "text",
      "name": "text"
    }
  },
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": false
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "https://example.com"
          }
        }
      ],
      "metadata": {
        "subject": "text"
      }
    }
  }
}

Send a plain text email

To send a plain text email message with the above endpoint set the request body as follows:

{
 "receiver": {
   "contacts": [
     {
       "identifierValue": "[e-mail]"
     }
   ]
 },
 "body": {
  "type": "text",
  "text": {
    "text": "Single text message"
  }
}
}

Send a html email

To send a html email message with the above endpoint set the request body as follows. For email clients that do not support html / rich content set the plain text fallback field.

{
  "receiver": {
    "contacts": [
      {
        "identifierValue": "[e-mail]"
      }
    ]
  },
 "body": {
  "type": "html",
  "html": {
  "text": "Single text message",
  "html": "<p style=\"\">Single html message</p><p style=\"\"></p><p style=\"\">"
 }
}
}

HTML metadata

Within the HTML body object you can include a metdata object as follows:

body.metadata.html.subject = set the email subject

body.metadata.emailfrom.username = set the sender before the @ e.g. [e-mail]

body.metadata.emailfrom.displayname = set the display name appearing in users inbox e.g. Support team

body.metadata.headers.reply-to = the reply-to address

As an example:

{
  "receiver": {
    "contacts": [
      {
        "identifierValue": "[e-mail]"
      }
    ]
  },
 "body": {
  "type": "html",
   "html": {
  "text": "Single text message",
  "html": "<p style=\"\">Single html message</p><p style=\"\"></p><p style=\"\">",
        "metadata": {
        "subject": "Here is an Email!",
        "headers":{
        "reply-to": "[e-mail]"
        },
        "emailFrom": {
          "username": "support",
          "displayName": "Support Team"
        }
      }
   }
  }
}

Send a html message with attachments

To send an email with attached media, ensure that your media file is either publicly available or see uploading media

Add attachment objects to body.html.attachments[] as shown. Each attachment object has the following properties

mediaUrl = The URL location of the media

filename = The name of the file

inline = boolean (default false). See sending inline images

  {
  "receiver": {
    "contacts": [
      {
        "identifierValue": "[e-mail]"
      }
    ]
  },
  "body": {
    "type": "html",
    "html": {
      "text": "Single text message",
      "html": "<p style=\"\">Single html message</p><p style=\"\"></p><p style=\"\">",
      "metadata": {
        "subject": "Here is an Email with an attachment",
        "headers": {
          "reply-to": "[e-mail]"
        },
        "emailFrom": {
          "username": "support",
          "displayName": "Support Team"
        }
      },
      "attachments": [
        {
          "mediaUrl": "mediaurl",
          "filename": "image.png",
          "inline": false
        }
      ]
    }
  }
}

Send a html message with inline images

To send an email with images inline, ensure that your media file is either publicly available or see uploading media.

Add an array of attachments to body.html as above, but set body.html.attachments[].inline to true

Within body.html reference the image in an image tag and prefix the filename with cid:

For example

<img src="cid:imagetext.png">

 {
  "receiver": {
    "contacts": [
      {
        "identifierValue": "[e-mail]"
      }
    ]
  },
  "body": {
    "type": "html",
    "html": {
      "text": "Single text message",
      "html": "<p style=\"\">Single html message</p><p style=\"\"></p><p style=\"\"><p>INLINE IMAGE! <img src=\"cid:image.png\"></p>",
      "metadata": {
        "subject": "Here is an Email with an attachment",
        "headers": {
          "reply-to": "[e-mail]"
        },
        "emailFrom": {
          "username": "support",
          "displayName": "Support Team"
        }
      },
      "attachments": [
        {
          "mediaUrl": "mediaurl",
          "filename": "image.png",
          "inline": true
        }
      ]
    }
  }
}