Отправка по шаблону

Используйте интерфейс конструктора писем, чтобы составить макет письма в своем личном кабинете, а управлять его отправкой из своего приложения при помощи API. Указывайте параметры, чтобы персонализировать отправляемые email. При отправке параметры будут заменены на тексты из API запроса. Вносите корректировки в дизайн макета письма в личном кабинете, при этом оставляя без изменений код отправки писем. В личном кабинете в разделе "Автоматизация", выберите "Одиночное по шаблону" и создайте шаблон письма. Отправляйте письма по этому шаблону с параметрами. Для подстановки параметра в шаблоне используйте конструкцию [%имя параметра%], например [%name%], [%age%] и т.д.

Создание шаблонa

Вы можете создать шаблон письма, используя этот метод, или зайти в свой личный кабинет и создать новый шаблон в конструкторе писем в разделе «автоматизация» => «Одиночные по шаблону».

Пример JSON для запроса

{
  "from_email": "hello@world.com",
  "subject": "Hello World",
  "text": "Hello World",
  "html": "<h1>Hello World</h1>"
  "preset_params": [
    "name",
    "age"
  ]
}

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

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

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

{
  "id": 1,
  "from_email": "hello@world.com",
  "from_name": null,
  "subject": "Hello World",
  "html": true,
  "text": true,
  "state": "draft"
  "preset_params": [
    "name",
    "age"
  ]
}

POST /email/templates

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

Параметр	Описание	Обязательный
from_email	Адрес отправителя	Да
from_name	Имя отправителя
subject	Тема письма	Да
name	Название шаблона
text
html		Да
preset_params	Массив параметров для подстановки в шаблон

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

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

Атрибут	Описание
id	Идентификатор
from_email	Адрес отправителя
from_name	Имя отправителя
subject	Тема письма
name	Название шаблона
html
text
state	Статус (создается в статусе draft)
preset_params	Массив параметров для подстановки в шаблон

Статусы

Значение	Описание
draft	Черновик
pending	На модерации
active	Модерация пройдена
inactive	Пауза
canceled	Отменена

Получение списка шаблонов

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

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

Данный метод поддерживает постраничную выдачу результатов.

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

{
  "total_count":3,
  "total_pages":1,
  "page_number":1,
  "page_size":25,
  "collection":[
    {
      "id":1,
      "name":"My Template"
    }
  ]
}

GET /email/templates

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

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

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

{
  "id": 1,
  "name": null,
  "subject": "Hello world!",
  "from_email": "hello@world.com",
  "from_name": "Mr.Hello",
  "state": "active",
  "preset_params": [
      "age",
      "name"
  ],
  "html": true,
  "text": true
}

GET /email/templates/:template_id

где: template_id - идентификатор шаблона

Отправка шаблона на модерацию

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

curl -X PATCH https://app.smsgold.ru/v1/email/templates/1/to_pending \
     -H 'Content-Type: application/json'    \
     -H 'Authorization: Bearer $API_TOKEN'

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

{
  "id": 1,
  "name": "Hello World",
  "subject": "Hello World",
  "from_email": "hello@world.com",
  "from_name": null,
  "state": "pending",
  "preset_params": [
      "age",
      "name"
  ],
  "html": true,
  "text": true
}

PATCH /email/templates/:template_id/to_pending

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

Пример JSON для запроса

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

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

Параметр	Описание	Обязательный
to	email получателя	Да
params	Параметры подстановки	Нет
payment	Способ тарификации сообщения. Возможные значения: subscriber_priority credit_priority subscriber credit Значение по умолчанию: subscriber_priority	Нет

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

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

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

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

curl -X POST https://app.smsgold.ru/v1/email/templates/:template_id/messages \
     -H 'Authorization: Bearer $API_TOKEN'      \
     -F to=to@example.com                       \
     -F params[name]=Ivan                       \
     -F attachments[]=@/path/to/file1           \
     -F attachments[]=@/path/to/file2

POST /email/templates/:template_id/messages

где: template_id - идентификатор шаблона

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

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

Атрибут	Описание
id	Идентификатор сообщения
to	Адрес получателя
status	Статус сообщения
events	Информация о событиях

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

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

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

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

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

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

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