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 | Letter 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 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 For example: |
ExtraData (optional) |
string | An object with the data which will be specified in the callback with the message status. Any |
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. |
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¶
{
"result": [
{
"index":0,
"address":"recipient.1@email.com",
"messageId":"dwY4BSnjQ2X"
},
{
"index":1,
"address":"recipient.2@email.com",
"messageId":"dwY4BSnjQ2i"
}
],
"description":"ok"
}
{
"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. |
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¶
[
{
"messageId": "dRJ7nkr99WF",
"ts": 1636976602504,
"status": "SENT",
"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"
}
}