EMAIL¶

Sending¶

To send Email messages it is required to:

Create the sender's domain. It could be done in personal account or through the technical support.
Call POST /email/messages, sending email letter parameters in the request body with the authorization data in the header.

Request parameters¶

Parameter	Data type	Description
Recipients	array[Recipients]	Recipient's data array.
Sender	Sender	Sender's data.
Subject	string	Email subject.
Body	Body	Letter body.
AttachmentsIds (optional)	array[string]	Files array attached to the letter.
CheckUnsubscription (optional)	boolean	Сhecking if the recipient of the letter has unsubscribed. If `true`, the user's unsubscribes will be requested from the contact base. `False` by default. If the response indicates that the email is unsubscribed from mailing lists of this company, then the letter will not be sent to the address.

Attention

If you want to attach files to the letter, at first you should call POST /files/files for every file separately. The response will contain the fileId parameter. All received fileId are specified in the AttachmentsIds array.

Recipients¶

Parameter	Data type	Description
Address	string	Recipient's email address.
Name (optional)	string	Recipient's name.
MergeFields (optional)	string	Custom macros in the form of a JSON object for placing them in the text of the letter (the `Body` object). For example: `{ "Birthday": "03/12/1999", "Name ": "Maria" }`
ExtraData (optional)	string	An object with the data which will be specified in the callback with the message status. Any `"key"` array: `{ "key1": "value1", "key2": "value2" }`

Sender¶

Parameter

Data type

Description

Address

string

Sender's email address.

The domain must first be created and approved.

Name
(optional)

string

Sender's name.

Up to 150 characters.

Body¶

It is necessary to fill one of the parameters: either Html or PlainText.

Parameter	Data type	Description
Html (optional)	string	Email body in HTML format.
PlainText (optional)	string	Email body in Plaintext format, all tags are displayed as plain text.

Attention

In addition to custom macros in the MergeFields parameter (the Recipients object), the letter body can also contain macros:

[Unsubscribe]
[WebVersion]

The [Unsubscribe] macro must be specified in Body, otherwise the letter will not be sent.

Request example¶

{
  "Recipients": [
    {
      "MergeFields": { "Name": "James" },
      "Address": "james@jamesmail.ru",
    }
  ],
  "CheckUnsubscription": true,
  "Sender": {
    "Address": "info@test.com",
    "Name": "TestShop"
  },
  "Subject": "Test message",
  "Body": {
    "Html": "<p>[Name], Welcome!</p>[Unsubscribe]"
  },
  "AttachmentsIds": [
    "312e628f-65dc-4d1d-a12e-64d86b6c06ca.png"
  ]
}

Response parameters¶

Parameter	Data type	Description
result	array[object]	Array with data of each of the messages sent. To be given with `"code": "ok"` only.
result.index	integer	Sequence number of the recipient from the array of passed recipients (the Recipients object).
result.address	string	Recipient's email address.
result.messageId	string	Message ID.
Description	string	Shows the result of message processing: 1.`ok` - processed successfully. 2. `Validation failed` - validation failed.
reasons	array	An array of the errors that occurred while processing the message. To be given with `"Description": "Validation failed"` only.
Reasons.Key	string	Error code.
Reasons.Reference	string	A reference to the parameter where the error has occurred.

Response example¶

OK

{
  "result": [
    {
      "index":0,
      "address":"recipient.1@email.com",
      "messageId":"dwY4BSnjQ2X"
    },
    {
      "index":1,
      "address":"recipient.2@email.com",
      "messageId":"dwY4BSnjQ2i"
    }
  ],
  "description":"ok"
}

VALIDATION FAILED

{
  "Description":"Validation failed",
  "Reasons": [
    {
      "Key":"validation.recipients.must.be.greather.then.0",
      "Reference":"recipients"
    }
  ]
}

Callbacks¶

How to enable

To set up callbacks with message statuses, please contact your account manager or technical support.

Possible statuses¶

Code	Description
ACCEPTED	The message has been accepted.
SENT	The message has been sent to the operator network.
DELIVERED	The message has been delivered to the user.
EXPIRED	The message lifetime has expired.
OPENED	The message has been read by the user.
CLICKED	The recipient has followed the link in the message.
BOUNCED	Failed to deliver the message (hard bounce email).
REJECTED	The message has been rejected by the operator or Devino.Online.
SUBSCRIBED	The recipient has subscribed.
UNSUBSCRIBED	The recipient has unsubscribed.
COMPLAINED	The recipient has complained.

Callback example¶

[
  {
    "dateTime": "2023-04-04T05:56:56.313Z",
    "userData": null,
    "contactId": null,
    "messageId": "dRJ7nkr99WF",
    "taskId": 0,
    "event": "ACCEPTED",
    "email": "example@devinotele.com"
  }
]

Put the file into storage¶

To attach a file to an email letter, you should first put this file into storage. To do this, call POST /files/files passing the file parameters in the header with the authorization data.

Request parameters¶

Parameter Data type Description

category string Reserved value EMAIL_ATTACHMENT.

file

string

Link to the file.

You can upload files in formats: .xls, .xlsx, .doc, .docx, .pdf, .jpg, .jpeg, .png, .img, .bmp, .rar, .txt

Request example¶

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

Response parameters¶

Parameter	Data type	Description
fileId	string	File ID. It must be specified in the sending request of the email.
publicUrl	string	File URL for download.

Response example¶

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

Details¶

To get the sent messages detailed information, you need to call GET /email-statistics/statistics/detail, sending filter parameters with the authorization data in the header.

Request parameters¶

Parameter	Data type	Description
limit	integer	The number of messages in the search results.
offset	integer	Search results offset. For example, if the number `5` is specified in the parameter, the received array of messages will be displayed only from the 5 in the pull.
taskId (optional)	integer	Message campaign ID for which you want to get the details. Used in required combination with the other parameters.
triggerId (optional)	integer	Message campaign trigger ID. Used in required combination with the other parameters.
dateTimeFrom (optional)	datetime	Start date of the message search. Used in required combination with the other parameters. The format is `YYYY-MM-DD+hh:mm:ss`.
dateTimeTo (optional)	datetime	End date of the message search. Used in required combination with the other parameters. The format is `YYYY-MM-DD+hh:mm:ss`.
messageIds (optional)	array[integer]	Message IDs for which you want to get the details. Used in required combination with the other parameters.
order (optional)	string	How to display the request results. Possible values: ○ `ASC` - in ascending order. ○ `DESC` - in descending order.
orderBy (optional)	string	Field by which to sort the request results.
recipient (optional)	string	Recipient's email address.
sourceAddress (optional)	string	Sender's email address.
status (optional)	string	The messages status in the request results. Possible values: ○ `DELIVERED` - the message has been delivered to the user. ○ `IN_PROGRESS` - the message is in the process of being sent to the operator. ○ `READ` - the message has been read by the user. ○ `REDIRECT` - the recipient has followed the link in the message. ○ `UNDELIVERED` - unable to deliver the message. ○ `SUBSCRIBED` - the recipient has subscribed. ○ `UNSUBSCRIBED` - the recipient has unsubscribed.
timeOffset (optional)	integer	Recipient's time zone.
userId (optional)	integer	Campaign sender user ID.

Parameters combinations¶

To get the correct request results, you should use one of these parameters combinations in accordance with the list:

Message campaign ID: taskId
Message campaign ID and trigger ID: taskId, triggerId
Start and end dates for the message search: dateTimeFrom, dateTimeTo
Message campaign ID, trigger ID; start and end dates for the message search: taskId, triggerId, dateTimeFrom, dateTimeTo
Message IDs: messageIds

Fields for `orderBy` parameter¶

Used in the orderBy parameter to sort the search results.

Field name	Description
COMPANY_ID	Company ID.
COMPANY_NAME	Company name.
EVENT_DATE_TIME	Date and time the status of the message was last updated.
MESSAGE_ID	Message ID.
PRICE	Message price.
RECIPIENT	Recipient's email address.
SENT_DATE_TIME	Date and time the message was sent.
SOURCE_ADDRESS	Sender's email address.
SOURCE_NAME	Sender's name.
STATUS	Message status.
SUBJECT	Email subject.
TASK_ID	Campaign ID.
TASK_NAME	Campaign name.
TASK_TYPE	Campaign type.
TRIGGER_CONTACT_GROUP	The name of the contact list to which the campaign was sent. In the response will be indicated as a `list` parameter.
TRIGGER_SEGMENT	The name of the contact list segment to which the campaign was sent. In the response will be indicated as a `segment` parameter.
IS_CONTACT_GROUP_DELETED	Whether the contact list from which the message was sent has been deleted. In the response will be indicated as an `isListDeleted` parameter.
IS_TRIGGER_SEGMENT_DELETED	Whether the contact list, the contact from which the message was sent, has been deleted. In the response will be indicated as an `isSegmentDeleted` parameter.
TRIGGER_ID	Campaign trigger ID.
USER_ID	Sender's user ID.
USER_LOGIN	Sender's user login.

Request examples¶

With dates

curl -X GET https://api.devino.online/email-statistics/statistics/detail?dateTimeFrom=2023-02-12+00:00:00&dateTimeTo=2023-02-24+00:00:00&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

With task ID and trigger ID

curl -X GET https://api.devino.online/email-statistics/statistics/detail?taskId=8742&triggerId=2312&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Response parameters¶

Parameter	Data type	Description
data	array[object]	An array of objects with detailed information on each message. The parameters are defined by the fields that were set in the original request.
size	integer	Number of items per page and messages in search results. Set by `limit` parameter.
offset	integer	Search results offset. For example, if the number `5` is specified in the parameter, the received array of messages will be displayed only from the 5 in the pull.
number	integer	The number of the received page. Defined by the `offset` parameter. ○ If the `offset` parameter value is `0` with any `limit` parameter value, then the page number will be `1`. ○ If the `offset` will be greater than `0` but less than the `limit` parameter value, the page number will be `2`. For example, with `"offset": 5` and `"limit": 10` the `number` parameter value will be `2`. ○ If the `offset` will be greater than `limit`, the page number will be determined by integer division of `offset` by `limit` plus 1 (`offset` / `limit` + 1). For example, with `"offset": 1000` and `"limit": 50`, the `number` parameter value will be `21` (`1000` / `50` + 1 = `21`).
pageExists	boolean	Whether the displayed page exists.
total	integer	The total number of messages for which the details can be received.
pages	integer	The total number of pages for which the details can be received. Determined by integer division of the `total` parameter by `limit` (`total` / `limit`).
more	boolean	Indicator: whether there are pages after the current one specified in the `number` parameter.

Response example¶

{
  "result": {
    "offset": 1000,
    "number": 21,
    "size": 50,
    "pageExists": true,
    "data": [
      {
        "messageId": "234567865432456787634",
        "recipient": "recipient@example.com",
        "sourceAddress": "sender@example.com",
        "sourceName": "sendersName",
        "sentDateTime": "2022-12-14 05:55:32",
        "status": "DELIVERED",
        "eventDateTime": "2022-12-14 05:54:52",
        "subject": "Special event",
        "companyId": 234,
        "companyName": "Company",
        "userId": 88,
        "userLogin": "79991112233",
        "taskId": 6666666,
        "triggerId": "22569",
        "price": "1.0000",
        "isListDeleted": false
      },
      ...
    ],
    "more": true,
    "pages": 100,
    "total": 1000
  }
}

Message statistics¶

To get the general statistics on message statuses, you need to call GET /omni-statistics-exporter/export/statistics/sliced-by-event-time, sending filter parameters with the authorization data in the header.

Request parameters¶

Parameter	Data type	Description
groupBy	string	Results grouping: ○ `NONE` - no grouping ○ `YEAR` - by year ○ `MONTH` - by month ○ `WEEK` - by week ○ `DAY` - by day ○ `HOUR` - by hour
dateTimeFrom	datetime	Start of the date range. The format is `YYYY-MM-DD+hh:mm:ss`.
dateTimeTo	datetime	End of the date range. The format is `YYYY-MM-DD+hh:mm:ss`.
charset (optional)	string	Encoding of the output. Possible values: CP1251 and UTF8.
taskId (optional)	integer	Campaign ID for which the statistics is needed.
triggerId (optional)	integer	Campaign trigger ID for which the statistics is needed.
userId (optional)	integer	Sender's user ID.
zoneOffset (optional)	integer	Recipient's time zone. The format is offset in minutes, for example, `180` for Moscow (GMT+3).

Request example¶

curl -X GET https://api.devino.online/email-stat/statistics/sliced-by-event-time?startDate=2023-02-12+00:00:00&endDate=2023-04-12+00:00:00&groupBy=MONTH
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Response parameters¶

The response data is formatted as a table with the parameters:

Info

The last table line indicates the statistics for the entire period.

Parameter	Description
Send date	Statistics collection date depending on the value of the `groupBy` parameter.
Sent	The number of messages accepted for sending.
Delivered	The number of delivered messages.
Delivery rate	The percentage of messages delivered out of the total.
Bounced	The number of undelivered messages (hard bounce email).
Bounce rate	The percentage of undelivered messages (hard bounce email).
Opened	The number of messages read by the recipient.
Open rate	The percentage of messages read by the recipient.
Clicked	The number of messages where the recipient followed the link.
Click to Open Rate	The percentage of messages where the recipient clicked on the link, based on the number of messages read. For example, if a message was opened 100 times and link from it was followed 20 times, then the parameter value will be `20`.
Unsubscribed	The number of messages where the recipient unsubscribed.
Unsubscribe Rate	Percentage of messages where the recipient unsubscribed.
Complained	The number of messages the recipient marked as spam.
Spam rate	The percentage of messages the recipient marked as spam.

Response example¶

Send date;Sent;Delivered;Delivery rate;Bounced;Bounce rate;Opened;Open rate;Clicked;Click to Open Rate;Unsubscribed;Unsubscribe Rate;Complained;Spam rate;
01.04.2022;0;0;0%;0;0%;0;0%;0;0%;0;0%;0;0%
01.05.2022;2;2;100%;0;0%;0;0%;0;0%;0;0%;0;0%
01.06.2022;914;904;98.91%;0;0%;0;0%;0;0%;0;0%;0;0%
01.07.2022;18;3;16.67%;0;0%;0;0%;0;0%;1;33.33%;0;0%
01.08.2022;0;0;0%;0;0%;0;0%;0;0%;0;0%;0;0%
01.09.2022;32;18;56.25%;0;0%;0;0%;1;0%;1;5.56%;0;0%
01.10.2022;4108031;4108041;100%;3;0%;6;0%;6;100%;0;0%;0;0%
01.11.2022;980578;980574;100%;0;0%;0;0%;0;0%;0;0%;0;0%
01.12.2022;5;4;80%;1;20%;0;0%;0;0%;0;0%;0;0%
01.02.2023;51;51;100%;0;0%;0;0%;0;0%;0;0%;0;0%
12.04.2022 - 12.04.2023;5089631;5089597;100%;4;0%;6;0%;7;116.67%;2;0%;0;0%

EMAIL¶

Sending¶

Request parameters¶

Recipients¶

Sender¶

Body¶

Request example¶

Response parameters¶

Response example¶

Callbacks¶

Possible statuses¶

Callback example¶

Put the file into storage¶

Request parameters¶

Request example¶

Response parameters¶

Response example¶

Details¶

Request parameters¶

Parameters combinations¶

Fields for orderBy parameter¶

Request examples¶

Response parameters¶

Response example¶

Message statistics¶

Request parameters¶

Request example¶

Response parameters¶

Response example¶

Fields for `orderBy` parameter¶