Messaging - Send message via email
NOTE:
To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.
This page walks you step-by-step through how to use Telesign Messaging to send an email message to an end user.
Content in messages
You can use Messaging to send transactional emails to end users you already have permission to send emails to. Cold outreach emails and any kind of unsolicited emails are not allowed.
In addition to text, your content can include:
- Your corporate or brand logo.
- A link to a corporate or brand video.
Your content must:
- Use links for images or videos you want to include representing the logo or brand. Telesign does not host images or videos on your behalf so links to the images or videos must be publicly accessible URLs.
CAUTION:
Additional content restrictions may apply depending on the country of the sender or the recipient. See Email restrictions in compliance rules and consult with our Customer Support Team to discuss any additional restrictions on email content.
Your content may be subject to review by Telesign. Not all content is eligible to be sent via Telesign Messaging using email. You are responsible for complying with all applicable laws and are subject to all compliance rules as appropriate for your transaction.
Before you begin
Make sure you have the following before you start:
- Set up email for your account: Before sending a message using email, you first need to work with our Customer Support Team to set up email for your account and to set up an email template. The Customer Support Team will also help you add your corporate or brand communications logo and other brand information for use with your emails.
- Transaction Callback Service: You need to have this set up so Telesign can send you delivery status updates for the message you send through the Messaging API. See Transaction Callback Service for setup instructions.
NOTE:
The Transaction Callback Service is also where you would receive inbound replies from the recipient of your message.
Steps
- Send a
POST /v1/omnichannel
request. Include the following param values:
Parameter | Value | Description | Required? |
---|---|---|---|
channels | array of channel objects | Add channel objects to the array in the order you want the service to try the channels. | yes |
channels[0] | {"channel":"email"} | Include email as the first channel. | yes |
channels[0].fallback_time | A time in seconds. | Specify the time to wait before cascading to the next channel. | no |
channels[1] | {"channel":"sms"} | Include sms as the backup channel. | yes (if SMS is used for backup) |
message.email.template | The name of this custom template | Specify your custom template that includes just text. | yes |
message.sms.template | text | Specify SMS as your preferred backup channel, using the text template. You can use a different backup channel and template if you prefer. | no |
message.sms.parameters.text | Some text. | Text to display in the message. | yes (if text template is used for backup) |
Request example
POST /v1/omnichannel HTTP/1.1
Content-Type: application/json
Authorization: Basic RkZGRkZGRkYtRUVFRS1ERERELTEyMzQtQUIxMjM0NTY3ODkwOlRFOHNUZ2c0NXl1c3Vtb042QllzQlZraCt5Uko1Y3pnc25DZWhaYU9ZbGRQSmRtRmg2TmVYOGt1bloyelUxWVdhVXcvMHdWNnhmdz09ZDfPvDkuGNsuqCFFO4neYIs=
Host: rest-ww.telesign.com
{
"channels": [
{
"channel": "email",
"fallback_time": 600
},
{
"channel": "sms"
}
],
"recipient": {
"phone_number": "11234567890",
"email": "[email protected]"
},
"message": {
"email": {
"template": "your-custom-template-name",
"parameters": {
"your-custom-template-param-1": "Your first custom template param value."
}
},
"sms": {
"template": "text",
"parameters": {
"text": "Our records indicate you requested a password reset. Please go to vero-finto.com to change your account password, If you did not initiate this request, please ignore this email."
}
}
},
"message_type": "ARN"
}
- If the request is processed successfully, you should see a response with a
3001
status code.
Response example
HTTP/1.1 200 OK
Server: nginx/1.17.7
Date: Wed, 14 Oct 2020 21:25:54 GMT
Content-Type: application/json
Content-Length: 137
Connection: keep-alive
Allow: GET,POST,HEAD
{
"status": {
"code": 3001,
"description": "Message in progress"
},
"reference_id": "35C8B5D509BC10689196FED2AD551B8A",
"external_id": null
}
- If the send in email format is successful, your end user receives an email message on their device.
- If the send in email format fails, the service tries to send the next specified backup channel (if any).
- Updates on the status of this email message are sent to the callback URL for your Transaction Callback Service. The general callback schema common to both this and other products is described on Transaction Callback Service. Modifications to the callback schema for this product are described on Messaging - Callback service. Search for these callbacks based on the reference ID in the response to your original Messaging request. Each callback payload includes an object with the status of the send for each channel that is tried.
Callback example
GET /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{
"reference_id": "35C8B5D509BC10689196FED2AD551B8A",
"external_id": "null",
"status": {
"code": 3000,
"description": "Delivered",
"last_channel": "sms",
"updated_on": "2020-05-04 22:07:01:226"
},
"channel_status": [
{"email": {
"code": 3056,
"description": "Message failed to deliver in specified fallback time",
"reference_id": "65C77D4A6C5C09085694EFB6C554D2BF",
"updated_on": "2020-05-04 22:06:03.837"
}},
{"sms": {
"code": 3000,
"description": "Delivered",
"reference_id": "65C77D4A6C5C09085694EFB6C558B4C7",
"updated_on": "2020-05-04 22:07:01:226"
}}
]
}
NOTE:
In addition to the reference ID for the Messaging transaction itself, the delivery status payload also includes a reference ID for the message-send on each channel. These can be useful for troubleshooting purposes.
Updated about 1 month ago