Одиночные сообщения

Отправка одиночного 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://app.smsgold.ru/v1/email/messages \
     -H 'Content-Type: application/json'        \
     -H 'Authorization: Bearer $API_TOKEN'      \
     -d '...JSON...'

Пример ответа в случае успеха

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

Пример запроса для отправки сообщения с вложениями

Вложения могут быть документами и медиа файлами. Суммарный размер вложений не должен превышать 5 Мбайт.

curl -X POST https://app.smsgold.ru/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

POST /email/messages

Параметры запроса

Параметр	Описание	Обязательный
from_email	Email отправителя	Да
from_name	Имя отправителя	Нет
to	Email получателя	Да
subject	Тема письма	Да
text	Текстовая версия письма	Должен присутствовать хотя бы один параметр: text или html
html	HTML версия письма	Должен присутствовать хотя бы один параметр: text или html
attachments	Массив с вложениями. Поддерживается только для запросов с типом содержимого multipart/form-data	Нет
payment	Способ тарификации. Возможные значения: subscriber_priority credit_priority subscriber credit Значение по умолчанию: subscriber_priority	Нет
smtp_headers	Список дополнительных SMTP заголовков письма	Нет

Способы тарификации сообщения

Значение	Описание
subscriber_priority	Тарифицируется "подписчик", если не доступны "подписчики", используется "письмо". Если нет "писем", возвращается ошибка.
credit_priority	Тарифицируется "письмо". Если нет "писем", используется "подписчик". Если нет "подписчиков", возвращается ошибка.
subscriber	Тарифицируется "подписчик". Если нет "подписчиков", возвращается ошибка.
credit	Тарифицируется "письмо". Если нет "писем", возвращается ошибка.

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут	Описание
id	Идентификатор сообщения
from_email	Адрес отправителя
from_name	Имя отправителя
to	Адрес получателя
subject	Тема письма
text	Текстовая версия сообщения
html	HTML версия сообщения
attachments	Массив имен вложенных файлов
status	Статус сообщения
events	Информация о событиях

Статусы сообщения

Статус	Описание
queued	Принято в очередь
sent	Отправлено, ожидается подтверждение доставки
delivered	Доставлено
skipped	Не отправлено. Получатель отписался или находится в списке проблемных получателей
soft_bounced	Не доставлено. Временно отклонено принимающей стороной
hard_bounced	Сообщение не может быть доставлено

Информация о событиях

Событие	Описание
open	Сообщение прочитано
redirect	Получатель перешел по ссылке
spam	Сообщение помечено как спам
unsubscribe	Пользователь отписался

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

Получение информации о сообщении

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

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

Пример ответа в случае успеха

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

GET /email/messages/:id

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут	Описание
id	Идентификатор
from_email	Адрес отправителя
from_name	Имя отправителя
to	Адрес получателя
subject	Тема письма
text	Текстовая версия сообщения
html	HTML версия сообщения
status	Статус сообщения
events	Информация о событиях

Статусы сообщения

Статус	Описание
queued	Принято в очередь
sent	Отправлено
delivered	Доставлено
skipped	Не отправлено
soft_bounced	Сообщение не доставлено
hard_bounced	Сообщение не может быть доставлено

Информация о событиях

Событие	Описание
open	Сообщение прочитано
redirect	Получатель перешел по ссылке
spam	Сообщение помечено как спам
unsubscribe	Пользователь отписался