Channel Identifier
In Comapi this channel can be referenced using: email
This identifier can be used in the rules array, and customBody sections.
Sending messages
Sending email messages is simple using the Comapi "One" API; simply ensure that in your rules or ruleSet you include the email channel, have enabled the email channel and follow the guidance below:
Enabling the Email Channel
Before using the email channel in the API you must first enable it in our portal and defining your default settings. To learn how to do this please see the email channel configuration page documentation.
Addressing your messages
To target who a App Messaging message is delivered to include a email in the to section of the request. For more information on profile Ids see the The One API Overview.
Subject lines
If you specify a title it will be used as a subject line for your emails.
The email body
You can specify the content of the email either as plain text, HTML or both. The messages body property holds the plain text version, the channelOptions.email.htmlBody can optionally hold the HTML version of the message.
Attachments
If you would like to add attachments to your emails then you will need to define your message content using Multi part messages instead of the body property.
From name
By default Comapi will use the From name specified in the email channel configuration page which typically would be your company name to send and receive email using our own email domain. You can override the name emails appear to be from using the channel option fromName as described below, to identify departments etc...
The way the fromName is typically displayed is highlighted above
Custom Domains
You can use your own domain to send and receive email, therefore ensuring a strong brand recognition of your emails and it allows you to manage your own email reputation. To use custom email domains you will need to contact us to arrange setup, apply the settings we give you to your domains DNS entries, and lastly reference it in your email sends request JSON. To specify a custom email domain to be used simply add a sendingDomain field to the channel options for email with the domain name in it.
To see what custom email domains you have setup for use, and the IP addresses associated with them please check the email channel configuration page and click on the Domains button.
Your Sending Email Address with Custom Domains
When sending email using a custom sendingDomain the email address the email is sent from with be constructed from a combination of the mailbox and sendingDomain specified e.g.
[mailbox]@[sendingDomain]
If the mailbox and sendingDomain are not specified then the email channels defaults will be used. The defaults can be set in the email channel configuration page.
Attachments
You can send attachments with your email such as images, files or any other valid MIME type. If you choose to add attachments then you must define the whole email as a series of message parts, and not set a body as the message parts will be used to construct this. The message parts are added as an array to the messageParts property, and ensure that your first message part is the email body content in either HTML (text/html) or plain text (plain/text), and then any other attachments you want. See the attachments example below for an example, and the message parts documentation for further details on how to use these.
{
"body": "Email send from Comapi",
"to": {
"email": "[email protected]"
},
"rules": [
"email"
]
}
{
"body": "Your order: ABC1245 has been dispatched.",
"title": "Your order has been dispatched",
"to": {
"email": "[email protected]"
},
"channelOptions": {
"email": {
"htmlBody": "<h2>Order Dispatched</h2><p>Order number: <b>ABC1245</b> has been dispatched</p>"
}
},
"rules": [
"email"
]
}
{
"body": "Your order: ABC1245 has been dispatched.",
"title": "Your order has been dispatched",
"to": {
"email": "[email protected]"
},
"channelOptions": {
"email": {
"fromName": "Acme Logistics"
}
},
"rules": [
"email"
],
"metadata": {
"data": "My correlation data"
}
}
{
"body": "Your order: ABC1245 has been dispatched.",
"title": "Your order has been dispatched",
"to": {
"email": "[email protected]"
},
"channelOptions": {
"email": {
"fromName": "Acme Logistics",
"mailbox": "no-reply",
"sendingDomain": "notifications.acmelogistics.com"
}
},
"rules": [
"email"
],
"metadata": {
"data": "My correlation data"
}
}
{
"title": "Your order: ABC1245 has been dispatched.",
"to": {
"email": "[email protected]"
},
"channelOptions": {
"email": {
"fromName": "Acme Logistics",
"addUnsubscribeFooter": true,
"htmlUnsubscribeFooter": "<a href='%unsubscribe_url%'>Click here</a> to unsubscribe."
}
},
"rules": [
"email"
],
"messageParts": [
{
"name": "Body html",
"type": "text/html",
"data": "<h2>Item Repaired</h2><p>Your return number: <b>ABC1245</b> has been repaired and is being retuned to you</p>"
},
{
"type": "image/png",
"url": "http://cdn.dnky.co/3rdparty/comapi/images/laptop.png"
}
],
"metadata": {
"data": "My correlation data"
}
}
{
"title": "Email sends with Comapi",
"to": {
"email": "[email protected]"
},
"channelOptions":{
"email":{
"fromName": "Comapi",
"addUnsubscribeFooter": true,
"unsubscribeFooter": "<a href='%unsubscribe_url%'>Click here</a> to unsubscribe."
}
},
"rules": [
"email"
],
"messageParts":[
{
"name":"Body html",
"type":"text/html",
"data":"<h2>Image Attached</h2><p>You can attach files using both a URL or Base64 data.</p>"
},
{
"name":"comapi.png",
"type":"image/png",
"size": 2560,
"data":"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"
}],
"metadata": {"data": "My correlation data"}
}
Channel Options
The following additional channel options can be used to control the email channels most common options. To use the channel options create a object with your options in the requests channelOptions section in the email property:
| Property | Type | Description |
|---|---|---|
| fromName | string | The from name to use for the email. If not specified it will default to the from name set in the channel settings on the Comapi portal. |
| sendingDomain | string | The custom domain the email should be sent with. Note: The domain must be setup for use prior to using this option! |
| htmlBody | string | The email body in HTML format, if specified both a text/plain and text/html version of the email will be sent |
| mailboxName | string | The mailbox name to use. A mailbox is a virtual mailbox to allow partitioning of your email between departments Default from channel configuration will be used if not specified. |
| trackOpens | boolean | Indicates whether read receipts should be generated when emails are opened (uses a tracking image). The default is true |
| addUnsubscribeFooter | boolean | Indicates whether a footer with an unsubscribe link should be added to the message. The default is false |
| htmlUnsubscribeFooter | string | Custom content for the unsubscribe footer in the HTML version of the email. Defaults will be applied if not specified. The token %unsubscribe_url% should be used in the string where you want the unsubscribe URL merged. |
| unsubscribeFooter | string | Custom content for the unsubscribe footer in the plain text version of the email. Defaults will be applied if not specified. The token %unsubscribe_url% should be used in the string where you want the unsubscribe URL merged. |
{
"body": "Your order for pink fluffy slippers has been dispatched!",
"to": {
"email": "[email protected]"
},
"channelOptions": {
"email": {
"fromName": "Support",
"htmlBody": "<p>Your order for <font color='pink'>pink fluffy slippers</font> has been dispatched!</p>",
"trackOpens": false,
"addUnsubscribeFooter": true,
"unsubscribeFooter": "If you don't want anymore shipping updates change your contact options in the portal or click on the following link: %unsubscribe_url%",
"htmlUnsubscribeFooter": "<hr/><p>If you don't want anymore shipping updates change your contact options in the portal or <a href='%unsubscribe_url%'>click here</a> to unsubscribe.</p>"
}
},
"rules": [
"email"
]
}
{
"body": "Your order for pink fluffy slippers has been dispatched!",
"title": "Your order has been dispatched",
"to": {
"email": "[email protected]"
},
"channelOptions": {
"email": {
"fromName": "Acme Support",
"addUnsubscribeFooter": true,
"unsubscribeFooter": "Click on the following link to unsubscribe: %unsubscribe_url%"
}
},
"rules": [
"email"
]
}
Unsubscribe mechanism
If you opt to add a unsubscribe link to your email using the addUnsubscribeFooter and unsubscribeFooter channel options or simply embedding the token %unsubscribe_url% in your emails body, if your customer clicks on it, all subsequent emails sent to that email address will be stopped and a Failed receipt returned.
Custom Body
The email channel doe not support custom bodies, all features are covered in the main options and channel options.
Receipts and Inbounds
To receive feedback or inbound messages from email sends please see the following:
Allows you to receive email messages sent. Messages are delivered to a URL of your choosing using Comapi's webhook system. See the Inbound event in the Message Events section for more details.
To send an message in to Comapi via email you can use the email address that is shown in the portals email channel configuration page which will look something like this:
general|[email protected]
Comapi Portal's email channel settings
If you need to to know the status of messages you've sent using one of our "One" API, you can request that delivery receipts are forwarded to a URL of your choosing using Comapi's webhook system. See the events in the Message Events section for more details on the receipt events you can receive.
You can receive the following types of receipts:
- Sent
- Delivered
- Read
- Failed
Tracking email opens
If the trackOpens channel option is set to false then you will not receive Delivered or Read receipts. The default is to track opens of emails.
Check out our quick starts...
Check out our quick starts for simple code examples of how to send with the "One" API