База знаний

Отправка одного email сообщения

Пример json данных для запроса:

{
  "from_email":"alice@example.org",
  "from_name": "Alice",
  "to": "bob@example.org",
  "subject": "Hello",
  "text": "Hello, Bob!",
  "html": "<h1>Hello, Bob!</h1>",
  "payment": "credit",
  "smtp_headers": {
    "Client-Id": "123"
  }
}

Пример самого запроса может быть таким:

curl -X POST https://api.msndr.net/v1/email/messages \
     -H 'Content-Type: application/json'        \
     -H 'Authorization: Bearer $API_TOKEN'      \
     -d '...JSON...'

Здесь используется метод POST и ссылка /email/messages

Пример ответа на запрос если он был выполнен успешно:

{
  "id":1,
  "from_email":"alice@example.org",
  "from_name":"Alice",
  "to":"bob@example.org",
  "subject":"Hello",
  "text":"Hello, Bob!",
  "html":"<h1>Hello, Bob!</h1>",
  "attachments": [],
  "status":"queued",
  "events": {
    "open": 1,
    "redirect": {
      "http://foo.com": 2,
      "http://bar.com": 3
    },
    "spam": 1,
    "unsubscribe": 1
  }
}

Также вы можете отправить сообщение с вложениями. Пример такого запроса:

curl -X POST https://api.msndr.net/v1/email/messages \
     -H 'Authorization: Bearer $API_TOKEN'      \
     -F from_email=from@example.com             \
     -F to=to@example.com                       \
     -F subject='Mail with attachments'         \
     -F text='Hello world'                      \
     -F attachments[]=@/path/to/file1           \
     -F attachments[]=@/path/to/file2           \
     -F smtp_headers[Client-Id]=123

 
Параметры from_email ( email адрес с которого отправляется сообщение), to ( email адрес получателя), subject( тема письма) являются обязательными. From_name ( имя от которого отправляется сообщение) является необязательным параметром. Также должен быть обязательно задан один из параметров text ( текст в текстовом формате) или html ( текст в html формате). Attachments это массив с вложениями. Он поддерживается только в запросах с типом содержимого multipart/form-data.

Payment это способ тарификации сообщения. Он может принимать значения:

1.subscriber_priority
2.credit_priority
3.subscriber
4.credit

Если вы не задали какого
либо значения, то оно будет subscriber_priority (по умолчанию).

Smtp_headers это список заголовков , которые будут отправлены вместе с smtp сообщением.

Существует четыре способа тарификации сообщений:

subscriber_priority - плата берётся за подписчика. Если доступных подписчиков не осталось , то плата берётся за письмо. Если доступных писем не осталось то возвращается ошибка.

credit_priority - это когда плата берётся за письмо. Если доступных писем не осталось , то плата берётся за подписчика. Если свободных подписчиков не осталось , то возвращается ошибка.

Subscriber - это когда плата берётся за подписчика. Если доступных подписчиков не осталось , то возвращается ошибка.

Credit - плата берётся за письмо. Если доступных писем не осталось, то возвращается ошибка.

Поясним некоторые параметры, json ответа сервера на запрос отправки одиночного email сообщения

Все параметры и пояснения к ним представлены ниже:

Поясним какие статусы сообщений бывают и о чём они нам говорят.

Существуют шесть статусов сообщений:

Queued - означает  что сообщение принято в очередь

Sent – означает что сообщение отправлено и ожидает подтверждения о доставке

Delivered – означает что сообщение доставлено

Skipped – означает что сообщение не отправлено. Получатель отписался от ваших сообщений или находится в списке проблемных получателей.

soft_bounced – означает что сообщение не доставлено. Получатель временно отклонил ваше сообщение.

hard_bounced – означает что сообщение не может быть доставлено по каким-либо причинам.

Также рассмотрим какие события ( events ) бывают.

Есть четыре события:

Open – сообщение прочитано

Redirect – получатель прошёл по ссылке

Spam – получатель пометил ваше сообщение как спам

Unsubscribe – пользователь отписался от ваших сообщений.

Также просим вас заметить что если вы отправляете письма которые вызывают подозрение на спам, то вы будете получать ошибку 429. Что означает что вы ограничены на число сообщений в единицу времени. Это делается для того чтоб предотвратить спам рассылку. Если вы будете совершать рассылку только своим клиентам, на существующие email адреса, то количество возможных отправок сообщений в единицу времени будет увеличиваться, если ваше поведение будет подозрительным то наоборот.

Также вы можете получить некоторую информацию об отправленном сообщении

Для этого вам необходимо выполнить запрос:

curl -X GET https://api.msndr.net/v1/email/messages/1 \
     -H 'Content-Type: application/json'              \
     -H 'Authorization: Bearer $API_TOKEN'            \
     -d '...JSON...'

Где используется метод GET и ссылка:

/email/messages/:id

Где ID это идентификационный номер сообщения , вернул нам сервер в ответе приведённом выше.

Если запрос будет выполнен успешно то вы например можете получить следующий ответ:

{
  "id":1,
  "from_email":"alice@example.org",
  "from_name":"Alice",
  "to":"bob@example.org",
  "subject":"Hello",
  "text":"Hello, Bob!",
  "html":"<h1>Hello, Bob!</h1>",
  "status":"queued",
  "events": {
    "open": 1,
    "redirect": {
      "http://foo.com": 2,
      "http://bar.com": 3
    },
    "spam": 1,
    "unsubscribe": 1
  }
}

Давайте поясним атрибуты json ответа от сервера:

Id – Идентификатор сообщения

from_email – email адрес отправителя

from_name – имя отправителя

to – email адрес получателя

subject – тема сообщения

text – текстовая версия сообщения

html – html версия сообщения

status – статус сообщения

events - информация о событиях связанных с этим сообщением

Поясним статусы сообщения , которые бывают при ответе на такие запросы:

Поясним события ( events ) , которые бывают в ответе на такие запросы:

Отправка одного сообщения по заданному шаблону

Для начала вам нужно будет создать шаблон. Для этого в личном кабинете в разделе "Автоматизация", выберите "Одиночное по шаблону" и создайте шаблон письма. Можно отправлять письма по этому шаблону с параметрами. Для того чтоб это можно было сделать, необходимо в шаблоне подставить нужные параметры при помощи конструкции  [%имя параметра%]. Например так:

[%name%], [%age%] и т.д.

Пример json данных для такого запроса:

{
  "to": "bob@example.org",
  "payment": "credit",
  "params": {
    "name": "Ivan",
    "age": "33"
  }
}

Пример самого запроса:

curl -X POST https://api.msndr.net/v1/email/templates/1/messages \
     -H 'Content-Type: application/json'        \
     -H 'Authorization: Bearer $API_TOKEN'      \
     -d '...JSON...'

Используется метод POST и ссылка /email/templates/:template_id/messages

Где template_id это идентификационный номер созданного шаблона в личном кабинете.

Запрос может иметь следующие параметры: