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 `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.
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"
  }
}