Skip to content

EMAIL

Sending

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

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: {{Unsubscribed}} и {{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

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

{
  "Recipients": [
    {
      "MergeFields": {"Name":"Ivan"},
      "Address": "ivan@mail.ru",
    }
  ],
  "Sender": {
    "Address": "info@test.com",
    "Name": "TestShop"
  },
  "Subject": "Test message",
  "Body": {
    "Html": "<p>{{Name}}, welcome!</p>"
  },
  "AttachmentsIds": [
    "312e628f-65dc-4d1d-a12e-64d86b6c06ca"
  ]
}

resp = requests.post(
    'https://api.devino.online/email/messages',
    json=messages
)
print(resp.json())

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.

Getting status

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

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

Request parameters

Parameter Data type Status Description
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