Skip to content

EMAIL

Sending

To send Email messages it is required to:

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

{
  "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"
  }
}