EMAIL¶

Sending¶

To send an EMAIL message it is required to create the domain. It can be done:

in Personal account page "Channel setting"
or contact technical support

After the domain is confirmed, you can use the method POST /email/messages sending message parameters in the body with authorization data in the heading.

Request parameters¶

Parameter	Data type	Description
Recipients	array[object]	Recipient data
Sender	string	Sender data
Subject	string	Message subject
Body	object	Message body
AttachmentsIds (optional)	array[integer]	Array of attached to the letter files

Attention

If you want to fill parameter AttachmentsIds you need to call POST /files/files, get fileId and specify it in AttachmentsIds

Recipients¶

Parameter	Data type	Description
MergeFields (optional)	string	Custom macros like "key":"value" For example:
ExtraData (optional)	string	Additional information like "key":"value"
Address	string	Recipient address
Name (optional)	string	Recipient name

Sender¶

Parameter	Data type	Description
Address	string	Sender address
Name (optional)	string	Sender name

Body¶

Parameter	Data type	Description
Html (optional)	string	Message body like html
PlainText (optional)	string	Message body "as is", all tags are displayed as plain text

Attention

Inside the Body one parameter must be filled: either Html or PlainText!

Attention

The message body can contain 2 more macros: [Unsubscribe] и [WebVersion], besides custom macros from Recipients.MergeFields.
The unsubscribe macro [Unsubscribe] must be specified in the Body, otherwise the message will not be sent.

Request example¶

curl -X POST /email/messages \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
 -H 'Content-Type: application/json' \
 -d '
{
  "Recipients": [
    {
      "MergeFields": {"Name":"Ivan"},
      "Address": "ivan@mail.ru",
    }
  ],
  "Sender": {
    "Address": "info@test.com",
    "Name": "TestShop"
  },
  "Subject": "Test message",
  "Body": {
    "Html": "<p>${contact.Name}, welcome!</p>"
  },
  "AttachmentsIds": [
    "312e628f-65dc-4d1d-a12e-64d86b6c06ca"
  ]
}' https://api.devino.online/email/messages

Response example¶

{
  "Result": [
    {
      "Index": "52342355",
      "Address": "info@test.com",
      "MessageId": "43432",
      "Code": "ok"
    }
  ],
  "Code": "ok"
}

Response parameters¶

Parameter	Data type	Description
Result	string	An array with answers for each of the messages sent
Code	string	Points out the result of message processing: ok - processed successfully validation_error - validation error internal_error - internal error
Description (optional)	string	Error description. Indicated if code is not ok
Reasons (optional)	Array[String, String]	An array of the errors which occurred while processing the message. To be given with code=REJECTED only
reasons.key	string	Error code.
reasons.ref (optional)	string	A reference to the parameter where the error occurred.

Result¶

Параметр	Тип данных	Описание и допустимые значения
Index	integer	Recipient position from an array of transferred Recipients
Address	string	Recipient address
MessageId	string	Message ID
Code	string	Points out the result of message processing: ok - processed successfully validation_error - validation error internal_error - internal error
Description (optional)	string	Error description. Indicated if code is not ok
Reasons (optional)	Array[String, String]	An array of the errors which occurred while processing the message. To be given with code=REJECTED only
reasons.key	string	Error code.
reasons.ref (optional)	string	A reference to the parameter where the error occurred.

Webhook¶

While creating the message status a POST request will be sent to the URL provided when sending the message in the Recipients.ExtraData callbackUrl parameter. 200 Ok is expected as the answer to the request.

In case the answer to the request is 500 Internal Error, there will be made 5 attempts to deliver the status with 1 minute interval.

Request example¶

JSON

{ 
   "messageId": "43Hndj432",
   "contactId": "3555c70819c42500-32786fc440885180",
   "taskId": "765",
   "triggerId": "543",
   "email": "ivanov@test.com",
   "event": "ACCEPTED",
   "dateTime": "2020-07-013 10:00:07",
   "clientInfo": {
   "platform": "DESKTOP",
   "operatingSystem": "Windows",
   "browser": "Chrome"
   },   
   "options": {
     "options1": "options1-123",
     "options2": "options2-123"
   }
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<messageEventDtos>
   <messageEventDto>
      <channel>EMAIL</channel>
      <messageId>43Hndj432</messageId>
      <ts>1607437519827</ts>
      <status>CLICKED</status>
      <browser>Chrome</browser>
      <os>Windows</os>
      <callbackData>
         <entry>
            <key>UserId</key>
            <value xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">UserId-123</value>
         </entry>
      </callbackData>
      <contactId>3555c70819c42500-32786fc440885180</contactId>
      <taskId>765</taskId>
      <triggerId>543</triggerId>
      <email>ivanov@test.com</email>
      <url>https://test.com/</url>
   </messageEventDto>
</messageEventDtos>

Request parameters¶

Parameter	Data type	Status
messageId	long	An unique message ID on the platform
contactId	string	An unique contact ID
taskId	long	An unique task ID
triggerId	long	An unique trigger ID
email	string	Email
event	string	Status (Possible statuses)
url	string	url the recipient clicked on (transmitted only with CLICKED status)
dateTime	string	Status date
clientInfo	object	Client information (transmitted only with OPENED, CLICKED, UNSUBSCRIBED statuses) Filled as follows: { "platform": "DESKTOP", //platform operatingSystem: "Windows", //operating system "browser": "Mozilla/4.0" //browser }
options	array[object]	Array of "key":"value" type parameters

Possible statuses¶

Parameter	Description
ACCEPTED	The message has been accepted
REJECTED	The message has been rejected by the operator or Devino
SENT	The message has been sent to the operator network
BOUNCED	Failed to deliver the message
DELIVERED	The message has been delivered to the user
OPENED	The message has been read by the user
CLICKED	The recipient has followed the link in the message
UNSUBSCRIBED	The recipient has unsubscribed
COMPLAINED	The recipient has complained
SUBSCRIBED	The recipient has subscribed

Put a file in the repository¶

To put the file in the repository (for further attachment to email) it is required to call POST /files/files sending message parameters in the body with authorization data in the heading.

Request parameters¶

Parameter	Data type	Description
category	string	Reserved value EMAIL_ATTACHMENT
file	file	File

Request example¶

curl -X POST /files/files?category=EMAIL_ATTACHMENT \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
 -H 'Content-Type: multipart/form-data' \
 -F 'file=@letter.png;type=image/png'

Response example¶

{
  "result": {
    "fileId": "efc1c054-9d65-4c21-b01f-cb0986c2dccb",
    "publicUrl": "http://files.local/emailAttachments/efc1c054-9d65-4c21-b01f-cb0986c2dccb"
  }
}

Response parameters¶

Parameter	Data type	Description
fileId	string	File ID
publicUrl	string	File URL for download