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 |
СheckUnsubscription | booolean | Сhecking if the recipient of the message has unsubscribed By default is false If true, the user's unsubscribes will be requested from the address-book service. If the response indicates that the email is unsubscribed from mailing lists of this company, then the message will not be sent to the address. In this case, the Rejected(9) event with the description rejected_unsubscribed will be written to Kafka |
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 \
-H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2' \
-H 'Content-Type: application/json' \
-d '
{
"Recipients": [
{
"MergeFields": {"Name":"James"},
"Address": "James@jamesmail.com"
}
],
"СheckUnsubscription": true,
"Sender": {
"Address": "info@test.com",
"Name": "TestShop"
},
"Subject": "Test message",
"Body": {
"Html": "<p>[Name], welcome!</p>[Unsubscribe]"
},
"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¶
Parameter | Data type | Description |
---|---|---|
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¶
[
{
"channel": "EMAIL",
"messageId": "dRJ7nkr99WF",
"ts": 1636976602504,
"status": "SENT",
"taskId": 0,
"triggerId": 0,
"email": "example@devinotele.com"
}
]
Request parameters¶
Parameter | Data type | Description |
---|---|---|
channel | string | Send channel ("EMAIL") |
messageId | long | An unique message ID on the platform |
ts | long | Indicates when the status object was created |
status | string | Status (Possible statuses) |
taskId | long | An unique task ID |
triggerId | long | An unique trigger ID |
string |
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 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 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 |