Transactional Messaging

The Transactional Messaging resource makes it possible to send transactional emails, SMS, and push notifications.

Reminder, unlike Broadcast campaigns or Automations that need to be created/sent from the Engage dashboard, Transactional messages (emails, SMS, push notifications) are programmatically sent from your application. Examples include password recovery emails and activity notification emails.

Send email

Send a transactional email through Engage or your connected Email Service Provider (ESP).

You cannot use the default sending profile for transactional emails. For improved deliverability reasons, you need to connect your domain to Engage or connect your ESP if you use any of the ones we support. You can do this via the Engage dashboard -> Settings -> Integrations.

Free accounts using Engage as their Email Service Provider (ESP) are limited to sending 100 transactional emails daily. If you have connected your ESP, also mind the send limits set by your ESP as well.

POST /v1/send/email

Parameters:

• from - An object containing the sender name and email. Ensure email has a hostname that covers the domain connected to Engage or registered with your ESP. If for example, your connected domain is awesome.co or mails.awesome.co, email should be in the form {any-username}@awesome.co.

• to - The recipient's email address or an array of email addresses.

• cc - Optional. An array of email addresses for the carbon copy field (cc).

• bcc - Optional. An array of email addresses for the blind carbon copy field (bcc).

• subject - The email subject.

• html - HTML content of the email. Optional, but one of html, template, or text must be included in request.

• text - Alternative text version of the email content.

• template - Template name or identifier if you want to send an email using a template you have already created on your Engage dashboard or on your ESP. Learn more

• template_variables - An object containing the variables for the specified template. These variables represent content parts and values that should be replaced in the template. Required if template is set.

• reply_to - Optional. A custom address that the email can be replied to.

• track_clicks - Optional. Set to true to enable click tracking.

• track_opens - Optional. Set to true to enable open tracking.

If successful, the request will return the ID of the sent message.

Example request data:

{
  "subject": "Hey",
  "from": {
    "email": "[email protected]",
    "name": "Awesome Co"
  },
  "to": ["[email protected]"],
  "html": "<p>Hello world</p>"
}

Example request data for an email based on a template:

{
  "subject": "Verify your email",
  "from": {
    "email": "[email protected]",
    "name": "Awesome Co"
  },
  "to": ["[email protected]"],
  "template": "signup-verification",
  "template_variables": {
    "link": "http://app.awesome.co/verification/email-123-hash",
    "ip": "127.0.0.1"
  }
}

Example response:

{ "id": "61bc1d13d2c9906305a5dd38" }

Example response (error):

{ "error": "The from address is not a valid email address." }

Send SMS

Send a transactional SMS.

POST /v1/send/sms

Parameters:

• from - The Sender ID registered with your service provider. For most providers, the message will fail if you use the wrong sender ID so always double-check.

• to - The recipient's phone number (with the country code). Numbers only.

• body - The message body.

• source - The SMS integration to send your SMS with. This must be any of twilio, termii, at (for Africa's Talking) or hollatags. If you have multiple SMS integrations in your Engage account, this lets you select the one to use. Even if you have one SMS integration, you still need to specify it here.

• track_clicks - Optional. Set to true to enable click tracking. This will rewrite links in the SMS so Engage can track clicks.

• channel - Optional. If you are using Termii (source: "termii"), you can set the channel for the SMS. This can either be generic or dnd. It defaults to generic if none is specified.

If successful, the request will return the ID of the sent message.

Example request data:

{
  "from": "12034914312",
  "source": "twilio",
  "to": "447845503401",
  "body": "Hello world. https://engage.so/",
  "track_clicks": true
}

{
  "from": "engage",
  "source": "termii",
  "to": "2348033413472",
  "body": "Hello world. https://engage.so/",
  "channel": "dnd"
}

Example response (successful):

{ "id": "61bc1d13d2c9906305a5dd38" }

Example response (error):

{ "error": "The senderid does not exist." }

Send Push Notifications

Coming soon.