Общие сведения
Данный документ содержит сведения о программном интерфейсе сервиса email рассылок (далее - «API»). Через API внешние приложения получают доступ к системе управлению списками получателей, отправке одиночных email сообщений, рассылок, а также прочий функционал для работы со списками получателей и статистикой рассылок
Базовый URL
Базовый URL для всех запросов
Альтернативный базовый URL для всех запросов
https://api-reserve.msndr.net/v1
Используйте альтернативный URL в случае, когда ваш IP заблокирован или имеет ограничения со стороны РКН.
Аутентификация
Для удостоверения подлинности запросов, в каждом обращении к API необходимо отправлять заголовок содержащий Ваш ключ.
Authorization: Bearer $API_TOKEN
Ключ для доступа к API можно получить в личном кабинете в разделе Автоматизация => API и SMTP => Параметры подключения API и SMTP
Держите Ваш ключ для доступа к API в секрете.
Формат обмена данных
Для обмена данными используется формат JSON, поэтому, в каждом запросе должен присутствовать заголовок
Content-Type: application/json
Все данные от сервера возвращаются так же, в формате JSON.
Получение списков данных (Collection)
Списки данных (Collection) - постраничный способ выдачи данных, используемый в некоторых методах. Для управления страницами выдачи списка данных в заголовках запроса необходимо передавать параметры page_number и page_size:
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/lists?page_number=2&page_size=3 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Поддерживаемые параметры
Параметр | Описание |
---|---|
page_number | Номер запрашиваемой страницы. По умолчанию: 1 |
page_size | Количество записей на странице. По умолчанию: 25 |
Если параметр page_size превышает максимально допустимый размер, то сервер ответит ошибкой со статусом 412:
{
"errors": [
{
"code": 412,
"detail": "Page size is too big. Max value is 100"
}
]
}
По умолчанию максимальный page_size равняется 100, если в описании конкретного метода не указано другое.
При выполнении запроса с использованием списка данных ответ будет возвращен в виде структуры:
Пример ответа со списком данных (Collection)
{
"total_count":23,
"total_pages":8,
"page_number":2,
"page_size":3,
"collection":[
{
"id":1,
"title":"My Recipients"
},
{
"id":2,
"title":"My Recipients #2"
},
{
"id":3,
"title":"My Recipients #3"
}
]
}
Ключ | Описание |
---|---|
total_count | Общее количество элементов "collection" |
total_pages | Количество страниц |
page_number | Номер текущей страницы |
page_size | Количество записей на странице |
collection | Массив возвращаемых данных |
Обработка ответа
Обработка ответа может осуществляться при проверке кода состояния HTTP запроса. Так же в случае неуспешного выполнения запроса, ответ содержит массив данных c описанием ошибок в формате JSON.
Пример ответа с ошибками
{
"errors":[
{
"code":400,
"detail":"subject is empty"
}
]
}
Коды ответов
Код | Описание |
---|---|
2xx | Запрос успешно выполнен |
400 | Неверные параметры |
401 | Аутентификация не пройдена |
402 | Недостаточно средств |
404 | Ресурс не найден |
415 | Неподдерживаемый тип данных |
422 | Ресурс не может быть обработан |
500 | Неизвестная ошибка |
Ограничения
Для предотвращения отправки нежелательных писем (спам), отправляемых по API или SMTP, в системе предусмотрен механизм приостановки отправки сообщений. Если для вашей учетной записи активировался механизм ограничения отправки, в личном кабинете в разделе API и SMTP, вы увидите предупреждение. Так же, при отправке письма в момент действующего ограничения вы увидите соответствующий ответ. Если вы считаете, что ограничения введены ошибочно, обратитесь в службу технической поддержи.
Примеры ответов
Для API:
{
"errors": [
{
"code": 429,
"detail": "Too many messages. Try again in 92 seconds."
}
]
}
Для SMTP:
$ telnet smtp.msndr.net 25
Trying 95.213.163.242...
Connected to smtp.msndr.net.
Escape character is '^]'.
220 smtp.msndr.net ESMTP service ready
ehlo sender
250-smtp.msndr.net
250-STARTTLS
250-AUTH PLAIN LOGIN
250-PIPELINING
250 8BITMIME
auth plain AHVzZXJAZXhhbXBsZS5vcmcAc29tZS1zdXBlci1wdXBlci1zZWNyZXQta2V5
550 Too many messages. Try again in 92 seconds.
Connection closed by foreign host.
Информация о балансе
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/balance \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"tariff" : {
"subscribers" : {
"total" : 1000,
"available" : 997
},
"credits" : 0,
"expires_at" : 1629273060
},
"balance" : 12965.96
}
GET /email/balance
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
tariff.subscribers.total | Итоговое количество подписчиков |
tariff.subscribers.available | Доступное количество подписчиков |
tariff.credits | Количество писем |
tariff.expires_at | Время окончания действия тарифа (timestamp) |
balance | Сумма на балансе |
Одиночные сообщения
Отправка одиночного 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 | Пользователь отписался |
Отправка по шаблону
Используйте интерфейс конструктора писем, чтобы составить макет письма в своем личном кабинете, а управлять его отправкой из своего приложения при помощи 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 | Тарифицируется "письмо". Если нет "писем", возвращается ошибка. |
Группы получателей
Создание группы
Пример JSON для запроса
{
"title":"My Recipients"
}
Пример запроса
curl -X POST https://app.smsgold.ru/v1/email/lists \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id":1,
"title":"My Recipients"
}
POST /email/lists
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Название группы получателей. Должно быть уникальным | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор созданной группы |
title | Название группы |
Получение списка групп
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/lists \
-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,
"title":"My Recipients"
},
{
"id":2,
"title":"My Recipients #2"
},
{
"id":3,
"title":"My Recipients #3"
}
]
}
GET /email/lists
Ответ сервера
Ответ сервера содержит коллекцию групп получателей. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор группы |
title | Название группы |
Получение информации о группе
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/lists/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"id":1,
"title":"My Recipients"
}
GET /email/lists/:id
где: id - идентификатор группы для запроса информации
Ответ сервера
Ответ сервера в формате JSON содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор группы |
title | Название группы |
Удаление группы
Пример запроса
curl -X DELETE https://app.smsgold.ru/v1/email/lists/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
DELETE /email/lists/:id
где :id - идентификатор группы для запроса информации
Ответ сервера
В случае успешного удаления сервер вернет пустой ответ со статусом 204.
Редактирование группы
Метод позволяет изменить название группы.
Пример JSON для запроса
{
"title":"New Title"
}
Пример запроса
curl -X PATCH https://app.smsgold.ru/v1/email/lists/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
-d '...JSON...'
Пример ответа в случае успеха
{
"id":1,
"title":"New Title"
}
PATCH /email/lists/:id
где :id - идентификатор группы для запроса информации
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Название группы получателей. Должно быть уникальным | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор отредактированной группы |
title | Название группы |
Параметры группы получателей
Создание параметра
Метод создает новый параметр в группе
Пример JSON для запроса
{
"title":"Age",
"kind": "numeric"
}
Пример запроса
curl -X POST https://app.smsgold.ru/v1/email/lists/1/parameters \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id":11,
"title":"Age",
"kind":"numeric",
"list_id":15
}
POST /email/lists/:id/parameters
где :id - идентификатор группы в которой создается параметр
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Название параметра | Да |
kind | Возможные значения:string numeric date boolean geo Значение по умолчанию: string |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор группы |
title | Название параметра |
kind | Тип параметра |
Получение списка параметров
Метод позволяет получить список параметров группы
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/lists/1/parameters \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{
"total_count":2,
"total_pages":1,
"page_number":1,
"page_size":25,
"collection":[
{
"id":1,
"title":"Name",
"kind":"string",
"list_id":1
},
{
"id":2,
"title":"Age",
"kind":"numeric",
"list_id":1
}
]
}
GET /email/lists/:id/parameters
где :id - идентификатор группы для получения списка параметров
Ответ сервера
Ответ сервера содержит коллекцию параметров группы получателей. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор параметра |
title | Название параметра |
kind | Тип параметра |
Изменение параметра
Метод позволяет изменить название и тип параметра группы
Пример JSON для запроса
{
"title":"Age",
"kind": "numeric"
}
Пример запроса
curl -X PATCH https://app.smsgold.ru/v1/email/lists/11/parameters/15 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id":11,
"title":"Age",
"kind":"numeric",
"list_id":15
}
PATCH /email/lists/:list-id/parameters/:id
где :list-id - идентификатор группы, :id - идентификатор параметра
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Название параметра | Нет |
kind | Возможные значения:string numeric date boolean geo При изменении типа параметра, его значения у получателей обнуляются |
Нет |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор параметра |
title | Название параметра |
kind | Тип параметра |
Удаление параметра
Метод удаляет параметр из группы получателей
Пример запроса
curl -X DELETE https://app.smsgold.ru/v1/email/lists/11/parameters/15 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
DELETE /email/lists/:list-id/parameters/:id
где :list-id - идентификатор группы, :id - идентификатор параметра
Получатели
Создание получателя
Метод создает получателя в группе получателей. При создании нового получателя вы можете прикреплять дополнительную информацию в виде тегов или параметров получателя. Параметры имеют название и значения, которые присоединены к получателю в рамках группы. Теги — это дополнительная информация (метка) получателя, которая прикреплена в рамках аккаунта и доступна во всех группах где будет создан получатель с аналогичным email
Вы можете использовать Параметры и Теги для персонализации макета письма и фильтрации при создании рассылок из личного кабинета.
Пример JSON для запроса
{
"email":"alice@example.org",
"unconfirmed": true,
"values":[
{
"parameter_id":"1",
"value":"Alice"
},
{
"parameter_id":"2",
"value":"22"
}
],
"tags":[
"buyer",
"regular customer"
]
}
Пример запроса
curl -X POST https://app.smsgold.ru/v1/email/lists/1/recipients \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id":1,
"email":"alice@example.org",
"confirmed":false,
"list_id":1,
"status": "active",
"values":[
{
"value":"Alice",
"kind":"string",
"parameter_id":1
},
{
"value":22.0,
"kind":"numeric",
"parameter_id":2
}
],
"tags":[
"buyer",
"regular customer"
]
}
POST /email/lists/:id/recipients
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
email получателя | Да | |
unconfirmed | Создать неподтвержденного получателя. Необходимо задать любое значение, например, true, t или 1. По умолчанию создается подтвержденный получатель | Нет |
values | Массив значений с параметрами получателя | Нет |
tags | Массив значений с тегами получателя | Нет |
Элементы массива значений с параметрами получателя
Параметр | Описание | Обязательный |
---|---|---|
parameter_id | ID параметра группы получателей | Да |
value | Значение параметра | Да |
Элементы массива значений с тегами получателя*
Массив значений тегов состоит из обычного массива. Например, ['tag1', 'tag2']
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
status | Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed |
values | Массив значений параметров |
tags | Массив значений тегов |
Элементы массива значений параметров
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение параметра |
Информация о получателе
Данный метод позволяет получить информацию о получателе по ID.
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/lists/1/recipients/2 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"id":2,
"email":"alice@example.org",
"confirmed":false,
"list_id":1,
"status": "active",
"values":[
{
"value":"Alice",
"kind":"string",
"parameter_id":1
},
{
"value":22.0,
"kind":"numeric",
"parameter_id":2
}
],
"tags":[
"buyer",
"regular customer"
]
}
GET /email/lists/:list_id/recipients/:id
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
list_id | ID группы | Да |
id | ID получателя | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
status | Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed |
values | Массив значений |
tags | Массив значений тегов |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Обновление получателя
Этот метод позволяет обновить параметры и теги получателя
Пример JSON для запроса
{
"email":"alice@example.org",
"values":[
{
"parameter_id":"1",
"value":"Alice"
},
{
"parameter_id":"2",
"destroy":"true"
}
],
"tags":[
{
"value":"buyer"
},
{
"value":"customer",
"destroy":"true"
}
]
}
Пример запроса
curl -X PATCH https://app.smsgold.ru/v1/email/lists/1/recipients/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id":1,
"email":"alice@example.org",
"confirmed":true,
"status": "active",
"list_id":1,
"values":[
{
"value":"Alice",
"kind":"string",
"parameter_id":1
}
],
"tags":[
"buyer",
"regular customer"
]
}
PATCH /email/lists/:list_id/recipients/:id
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
Email получателя | Да | |
values | Массив значений параметров получателя | Нет |
tags | Массив значений тегов | Нет |
run_triggers | Запустить связанные триггеры. Необходимо задать любое значение, например, true, t или 1. | Нет |
Элементы массива значений параметра values
Параметр | Описание | Обязательный |
---|---|---|
parameter_id | ID параметра группы получателей | Да |
value | Не может быть одновременно использован с параметром destroy | Нет |
destroy | Используется для удаления значения. Для удаления значения необходимо задать любое значение, например, true, t или 1. Не может быть использован одновременно с параметром value | Нет |
Элементы массива значений параметра tags
tags состоит из массива значений [ 'tag1', 'tag2', 'tag3' ]
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
status | Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed |
values | Массив значений |
tags | Массив значений тегов |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение параметра |
Список получателей
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/lists/1/recipients \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов. Максимальный page_size равняется 1000.
Пример ответа в случае успеха
{
"total_count":2,
"total_pages":1,
"page_number":1,
"page_size":25,
"collection":[
{
"id":1,
"email":"alice@example.org",
"confirmed":true,
"status": "active",
"list_id":1,
"values":[
{
"value":"Alice",
"kind":"string",
"parameter_id":9
},
{
"value":22.0,
"kind":"numeric",
"parameter_id":10
}
],
"tags":[
"buyer",
"regular customer"
]
},
{
"id":2,
"email":"bob@example.org",
"confirmed":true,
"status": "active",
"list_id":1,
"values":[
],
"tags":[
]
}
]
}
GET /email/lists/:id/recipients
Ответ сервера
Ответ сервера содержит коллекцию получателей группы. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор получателя |
Email получателя | |
confirmed | Подтвержден получатель или нет |
status | Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed |
values | Массив значений параметра получателей |
tags | Массив значений тегов |
Элементы массива значений values
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Удаление получателя
Пример запроса
curl -X DELETE https://app.smsgold.ru/v1/email/lists/1/recipients/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
DELETE /email/lists/:list_id/recipients/:id
Импорт большого количества получателей
POST /email/lists/:id/recipients/imports
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
recipients | Массив получателей. Максимальный размер 10000 | Да |
run_triggers | Запустить связанные триггеры. Возможные значения:trigger_any trigger_fresh |
Нет |
tags | Массив значений тегов | Нет |
callback_url | url, на который будет отправлен запрос после завершения импорта | Нет |
Массив получателей recipients
Параметр | Описание | Обязательный |
---|---|---|
Email получателя | Да | |
values | Массив значений параметров | Нет |
Элементы массива значений values
Параметр | Описание | Обязательный |
---|---|---|
parameter_id | ID параметра группы получателей | Да |
value | Значение параметра | Да |
Параметр run_triggers
Значение | Описание |
---|---|
trigger_any | Запустить связанные триггеры для всех получателей |
trigger_fresh | Запустить связанные триггеры только для новых получателей |
Ответ сервера
Параметр | Описание |
---|---|
id | Идентификатор импорта. В дальнейшем может использоваться для получения информации о ходе импорта |
status | Статус импорта |
callback_url | url, на который будет отправлен запрос после окончании импорта |
Пример JSON для запроса
{
"recipients":[
{
"email":"alice@example.org",
"values":[
{
"parameter_id":"1",
"value":"Alice"
},
{
"parameter_id":"2",
"value":"22"
}
]
},
{
"email":"bob@example.org",
"values":[
{
"parameter_id":"1",
"value":"Bob"
},
{
"parameter_id":"2",
"value":"11"
}
]
}
],
"tags":[
"buyer",
"regular customer"
]
}
Пример запроса
curl -X POST https://app.smsgold.ru/v1/email/lists/1/recipients/imports \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id":7,
"status":"queued",
"callback_url": null
}
Пример запроса после окончания импорта, если указан callback url
{
"id":7,
"status":"completed",
"callback_url":"https://my-callback-url.com/some-secret"
}
Поиск получателей
Метод осуществляет поиск получателя по email, например, чтобы определить в каких группах он присутствует.
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/recipients/search?email=foo@bar.com \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"total_count": 2,
"total_pages": 1,
"page_number": 1,
"page_size": 25,
"collection": [
{
"email": "foo@bar.com",
"recipients": [
{
"list_id": 1,
"list_title": "List #1",
"recipient_id": 1
},
{
"list_id": 2,
"list_title": "List #2",
"recipient_id": 2
}
]
}
],
"query": "test"
}
GET /email/recipients/search
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
Искомый адрес | Да |
Ответ сервера
Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
Email получателя | |
recipients | Массив, содержащий информацию о списках, в которых найден получатель |
Организации
Создание организации
Пример JSON для запроса
{
"name":"My Organization",
"address":"Lenina 40",
"country":"Russia",
"city":"Tomsk",
"phone":"+7-3822-123-456",
"zip":"634000"
}
Пример запроса
curl -X POST https://app.smsgold.ru/v1/email/organizations \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id":1,
"name":"My Organization",
"address":"Lenina 40",
"country":"Russia",
"city":"Tomsk",
"phone":"+7-3822-123-456",
"zip":"634000",
"current":true
}
POST /email/organizations
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
name | Да | |
address | Да | |
country | Да | |
city | Да | |
phone | Да | |
zip | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Список организаций
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/organizations \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{
"total_count":1,
"total_pages":1,
"page_number":1,
"page_size":25,
"collection":[
{
"id":1,
"name":"My Organization",
"address":"Lenina 40",
"country":"Russia",
"city":"Tomsk",
"phone":"+7-3822-123-456",
"zip":"634000",
"current":true
}
]
}
GET /email/organizations
Ответ сервера
Ответ сервера содержит коллекцию организаций. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Информация об организации
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/organizations/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"id":1,
"name":"My Organization",
"address":"Lenina 40",
"country":"Russia",
"city":"Tomsk",
"phone":"+7-3822-123-456",
"zip":"634000",
"current":true
}
GET /email/organizations/:id
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Организация по умолчанию
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/organizations/current \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"id":1,
"name":"My Organization",
"address":"Lenina 40",
"country":"Russia",
"city":"Tomsk",
"phone":"+7-3822-123-456",
"zip":"634000",
"current":true
}
GET /email/organizations/current
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Задать организацию по умолчанию
Пример запроса
curl -X PATCH https://app.smsgold.ru/v1/email/organizations/1/current \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"id":1,
"name":"My Organization",
"address":"Lenina 40",
"country":"Russia",
"city":"Tomsk",
"phone":"+7-3822-123-456",
"zip":"634000",
"current":true
}
PATCH /email/organizations/:id/current
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Изменение организации
Пример JSON для запроса
{
"name":"My Organization",
"address":"Lenina 40",
"country":"Russia",
"city":"Tomsk",
"phone":"+7-3822-123-456",
"zip":"634000"
}
Пример запроса
curl -X PATCH https://app.smsgold.ru/v1/email/organizations/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id":1,
"name":"My Organization",
"address":"Lenina 40",
"country":"Russia",
"city":"Tomsk",
"phone":"+7-3822-123-456",
"zip":"634000",
"current":true
}
PATCH /email/organizations/:id
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
name | ||
address | ||
country | ||
city | ||
phone | ||
zip |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Удаление организации
Пример запроса
curl -X DELETE https://app.smsgold.ru/v1/email/organizations/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
DELETE /email/organizations/:id
Рассылки
Создание рассылки
Метод создает рассылку со статусом Черновик. Для последующей отправки созданной рассылки используется метод Отправка рассылки или Отправка отложенной рассылки
Пример JSON для запроса
{
"from_email":"hello@world.com",
"subject":"Hello World",
"text":"Hello World",
"html":"<h1>Hello World</h1>",
"lists":[
{
"id":"1"
}
]
}
Пример запроса
curl -X POST https://app.smsgold.ru/v1/email/campaigns \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример запроса для создания рассылки с вложениями
curl -X POST https://app.smsgold.ru/v1/email/campaigns \
-H 'Authorization: Bearer $API_TOKEN' \
-F from_email=from@example.com \
-F subject='Mail with attachments' \
-F html='<h1>Hello world</h1>' \
-F attachments[]=@/path/to/file1 \
-F attachments[]=@/path/to/file2
Пример ответа в случае успеха
{
"id":1,
"from_email":"hello@world.com",
"from_name":null,
"html":"<h1>Hello World</h1>",
"text":"Hello World",
"state":"draft",
"recipients_count":10,
"purchase":{
"enable":true,
"subscribers":10,
"credits":0,
"deficit":0
},
"statistics":{
"delivered":1,
"bounced":0,
"delivering":0,
"uniq_open":0,
"total_open": 0,
"last_open_at": nil,
"uniq_click":0,
"total_click": 0,
"last_click_at": nil,
"unsubscription":0,
"spam":0
}
}
POST /email/campaigns
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
from_email | Email отправителя | Да |
subject | Тема письма в рассылке | Да |
from_name | Имя отправителя | Нет |
text | Текстовая версия письма | Нет |
html | HTML версия письма | Да |
lists | Массив групп получателей | Да |
Элементы массива групп получателей
Параметр | Описание | Обязательный |
---|---|---|
id | ID группы получателей | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор созданной рассылки |
from_email | Адрес отправителя |
from_name | Имя отправителя |
html | HTML версия письма |
text | Текстовая версия письма |
state | Статус (рассылка создается в статусе draft) |
recipients_count | Количество получателей в рассылке |
purchase | Информация о тарификации |
statistics | Статистика рассылки |
Статусы рассылки
Значение | Описание |
---|---|
draft | Черновик |
pending | На модерации |
delayed | Запланированная |
sending | Отправляется |
canceled | Отменена |
stopped | Остановлена |
completed | Завершена |
archived | В архиве |
Информация о тарификации
Атрибут | Описание |
---|---|
enable | Может принимать значение true (отправка возможна) или false (необходимо улучшить тариф) |
subscribers | Количество подписчиков которое будет списано из тарифа |
credits | Количество писем которое будет списано из тарифа |
deficit | Число на которое необходимо увеличить количество подписчиков или писем в тарифе |
Статистика
Атрибут | Описание |
---|---|
delivered | Количество доставленных сообщений |
bounced | Количество недоставленный сообщений |
delivering | Количество доставляющихся сообщений |
uniq_open | Количество уникальных открытий |
total_open | Количество открытий всего |
last_open_at | Timestamp последнего открытия |
uniq_click | Количество уникальных переходов |
total_click | Количество переходов всего |
last_click_at | Timestamp последнего перехода |
unsubscription | Количество отписок |
spam | Количество нажатий кнопки "спам" |
Отправка рассылки
Метод позволяет отправить рассылку, которая ранее была создана с помощью метода Создание рассылки
Пример запроса
curl -X PATCH https://app.smsgold.ru/v1/email/campaigns/1/deliver \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id":1,
"from_email":"hello@world.com",
"from_name":null,
"html":"<h1>Hello World</h1>",
"text":"Hello World",
"state":"sending",
"time_zone":"Fiji",
"start_at":"30.10.2022 01:00 UTC",
"recipients_count":10,
"purchase":{
"enable":true,
"subscribers":10,
"credits":0,
"deficit":0
},
"statistics":{
"delivered":1,
"bounced":0,
"delivering":0,
"uniq_open":0,
"total_open": 0,
"last_open_at": nil,
"uniq_click":0,
"total_click": 0,
"last_click_at": nil,
"unsubscription":0,
"spam":0
}
}
PATCH /email/campaigns/:id/deliver
Отправка отложенной рассылки
Метод позволяет отправить рассылку в заданное время, которая ранее была создана с помощью метода Создание рассылки
Пример JSON для запроса
{
"start_at": "30.10.2022 13:00",
"time_zone": "Fiji",
}
Пример запроса
curl -X PATCH https://app.smsgold.ru/v1/email/campaigns/1/schedule \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id":1,
"from_email":"hello@world.com",
"from_name":null,
"html":"<h1>Hello World</h1>",
"text":"Hello World",
"state":"sending",
"time_zone":"Fiji",
"start_at":"30.10.2022 01:00 UTC",
"recipients_count":10,
"purchase":{
"enable":true,
"subscribers":10,
"credits":0,
"deficit":0
},
"statistics":{
"delivered":1,
"bounced":0,
"delivering":0,
"uniq_open":0,
"total_open": 0,
"last_open_at": nil,
"uniq_click":0,
"total_click": 0,
"last_click_at": nil,
"unsubscription":0,
"spam":0
}
}
PATCH /email/campaigns/:id/schedule
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
id | ID созданной рассылки | Да |
start_at | Дата и время отправки | Нет |
time_zone | Часовой пояс | Нет |
Список часовых поясов
Название | UTC |
---|---|
International Date Line West | -12:00 |
American Samoa | -11:00 |
Hawaii | -10:00 |
Alaska | -09:00 |
Tijuana | -08:00 |
Arizona | -07:00 |
Saskatchewan | -06:00 |
Lima | -05:00 |
Santiago | -04:00 |
Brasilia | -03:00 |
Mid-Atlantic | -02:00 |
Azores | -01:00 |
UTC | +00:00 |
Paris | +01:00 |
Kaliningrad | +02:00 |
Moscow | +03:00 |
Tehran | +03:30 |
Samara | +04:00 |
Kabul | +04:30 |
Ekaterinburg | +05:00 |
Mumbai | +05:30 |
Kathmandu | +05:45 |
Almaty | +06:00 |
Rangoon | +06:30 |
Bangkok | +07:00 |
Hong Kong | +08:00 |
Osaka | +09:00 |
Adelaide | +09:30 |
Sydney | +10:00 |
Magadan | +11:00 |
Fiji | +12:00 |
Chatham Is. | +12:45 |
Samoa | +13:00 |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
from_email | Адрес отправителя |
from_name | Имя отправителя |
start_at | Дата и время отправки |
time_zone | Часовой пояс |
html | HTML версия письма |
text | Текстовая версия письма |
state | Статус |
recipients_count | Количество получателей |
purchase | Информация о тарификации |
statistics | Статистика |
Статусы
Значение | Описание |
---|---|
draft | Черновик |
pending | На модерации |
delayed | Запланированная |
sending | Отправляется |
canceled | Отменена |
stopped | Остановлена |
completed | Завершена |
archived | В архиве |
Информация о тарификации
Атрибут | Описание |
---|---|
enable | Может принимать значение true (отправка возможна) или false (необходимо улучшить тариф) |
subscribers | Количество подписчиков которое будет списано из тарифа |
credits | Количество писем которое будет списано из тарифа |
deficit | Число на которое необходимо увеличить количество подписчиков или писем в тарифе |
Статистика
Атрибут | Описание |
---|---|
delivered | Количество доставленных сообщений |
bounced | Количество недоставленный сообщений |
delivering | Количество доставляющихся сообщений |
uniq_open | Количество уникальных открытий |
total_open | Количество открытий всего |
last_open_at | Timestamp последнего открытия |
uniq_click | Количество уникальных переходов |
total_click | Количество переходов всего |
last_click_at | Timestamp последнего перехода |
unsubscription | Количество отписок |
spam | Количество нажатий кнопки "спам" |
Список рассылок
Метод позволяет получить весь список рассылок аккаунта.
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/campaigns?statistic=false \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{
"total_count": 1,
"total_pages": 1,
"page_number": 1,
"page_size": 25,
"collection": [
{
"id": 1,
"from_email": "test@example.com",
"from_name": "Test",
"html": "<p>test</p>",
"text": "test",
"state": "draft",
"recipients_count": 10,
"purchase": {
"enable": true,
"subscribers": 0,
"credits": 10,
"deficit": 0
},
"statistics":{
"delivered":1,
"bounced":0,
"delivering":0,
"uniq_open":0,
"total_open": 0,
"last_open_at": nil,
"uniq_click":0,
"total_click": 0,
"last_click_at": nil,
"unsubscription":0,
"spam":0
}
}
]
}
GET /email/campaigns
Ответ сервера
Ответ сервера содержит коллекцию рассылок. Подробнее об элементах коллекции в описании метода "Создание рассылки".
Поддерживаемые параметры
Параметр | Описание |
---|---|
statistic | Включать блок statistics в выдачу. Возможные значения: true, false. По умолчанию true. Выключение статистики существенно ускоряет работу метода. |
Информация о рассылке
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/campaigns/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"id":1,
"from_email":"hello@world.com",
"from_name":null,
"html":"<h1>Hello World</h1>",
"text":"Hello World",
"state":"sending",
"recipients_count":10,
"purchase":{
"enable":true,
"subscribers":10,
"credits":0,
"deficit":0
},
"statistics":{
"delivered":1,
"bounced":0,
"delivering":0,
"uniq_open":0,
"total_open": 0,
"last_open_at": nil,
"uniq_click":0,
"total_click": 0,
"last_click_at": nil,
"unsubscription":0,
"spam":0
}
}
GET /email/campaigns/:id
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор запрашиваемой рассылки |
from_email | Адрес отправителя |
from_name | Имя отправителя |
html | HTML версия письма |
text | Текстовая версия письма |
state | Статус |
recipients_count | Количество получателей |
purchase | Информация о тарификации |
statistics | Статистика рассылки |
Статусы рассылки
Значение | Описание |
---|---|
draft | Черновик |
pending | На модерации |
delayed | Запланированная |
sending | Отправляется |
canceled | Отменена |
stopped | Остановлена |
completed | Завершена |
archived | В архиве |
Информация о тарификации
Атрибут | Описание |
---|---|
enable | Может принимать значение true (отправка возможна) или false (необходимо улучшить тариф) |
subscribers | Количество подписчиков которое будет списано из тарифа |
credits | Количество писем которое будет списано из тарифа |
deficit | Число на которое необходимо увеличить количество подписчиков или писем в тарифе |
Статистика
Атрибут | Описание |
---|---|
delivered | Количество доставленных сообщений |
bounced | Количество недоставленный сообщений |
delivering | Количество доставляющихся сообщений |
uniq_open | Количество уникальных открытий |
total_open | Количество открытий всего |
last_open_at | Timestamp последнего открытия |
uniq_click | Количество уникальных переходов |
total_click | Количество переходов всего |
last_click_at | Timestamp последнего перехода |
unsubscription | Количество отписок |
spam | Количество нажатий кнопки "спам" |
Webhooks
Вы можете управлять вебхуками в кабинете сервиса, в разделе Автоматизация -> Webhooks, либо используя API описанный в этом разделе.
Механизм вебхуков позволяет получать POST запросы на указанный URL, о событиях, связанных с отправленными сообщениями. Вебхуки приходят раз в 10 минут группами не более 500 событий в одном запросе. Вы можете настроить типы сообщений, а также события, о которых хотите получать уведомления. Доступные типы сообщений: API/SMTP, рассылки, триггеры, одиночные по шаблону. Доступные события: Доставлено, Не доставлено, Пропущено, Открытие, Переход, Жалоба, Отписка.
Пример данных из полученного POST запроса:
{
"meta": {
"type": "campaign",
"id": 1,
"name": "Рассылка постоянным клиентам"
},
"events": [
{
"id": 1164,
"name": "delivered",
"email": "example@gmail.com",
"timestamp": 1684400000
}
]
Каждый запрос содержит параметры meta и events. Параметр meta это хеш который содержит информацию о том к чему относятся события из данного запроса.
Поля параметра meta
Поле | Пример | Значения | Обязательно | Описание |
---|---|---|---|---|
type | campaign | campaign - обычная рассылка, campaign_transactional - одиночные по шаблону, campaign_workflow - триггерная рассылка, api - API или SMTP трафик |
Да | Объект, с которым связаны пришедшие в вебхук события |
id | 1 | число | Да для всех типов кроме api | ID рассылки |
name | Рассылка постоянным клиентам | строка | Да для всех типов кроме api | Название рассылки |
Параметр events это массив событий связанных с meta
Поля элемента массива events
Поле | Пример | Значения | Обязательно | Описание |
---|---|---|---|---|
id | 1164 | Да | id сообщения | |
name | delivered | delivered - доставлено, skipped - пропущено (при отправке на отписанных), soft_bounced - не доставлено, hard_bounced - не доставлено, opened - открытие, unsubscribed - отписка, complained - жалоба, clicked - переход по ссылке |
Да | Название события |
example@gmail.com | Да | Email адрес | ||
timestamp | 1684400000 | Да | Время события | |
url | https://ya.ru | Да для clicked | Ссылка | |
user_agent | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36 | Да для clicked | Информация о браузере | |
ip | 1.1.1.1 | Да для clicked | Ip адрес | |
browser | Chrome | Да для clicked | Браузер | |
os | Windows | Да для clicked | Операционная система | |
device_type | Desktop | Да для clicked | Тип устройства | |
country | Russian Federation | Да для clicked | Страна | |
region | 46 | Да для clicked | Код региона | |
city | Saransk | Да для clicked | Город | |
delivery_status | 5.1.1 | Да для недоставленных | Код ответа | |
delivery_response | Invalid mailbox | Да для недоставленных | Текст ответа |
Пример для рассылки, в которой одно доставленное сообщение, открытие, переход и отписка.
{
"meta": {
"id": 1,
"name": "Рассылка постоянным клиентам",
"type": "campaign"
},
"events": [
{
"id": 1170,
"name": "delivered",
"email": "example@gmail.com",
"timestamp": 1684400000
},
{
"id": 1171,
"name": "opened",
"email": "example@gmail.com",
"timestamp": 1684401111
},
{
"id": 1172,
"name": "clicked",
"email": "example@gmail.com",
"timestamp": 1684402222,
"url": "https://ya.ru",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
"ip": "1.1.1.1",
"browser": "Chrome",
"os": "Windows",
"device_type": "Desktop",
"country": "Russian Federation",
"region": "46",
"city": "Saransk"
},
{
"id": 1173,
"name": "unsubscribed",
"email": "example@gmail.com",
"timestamp": 1684403333
}
]
}
Создание вебхука
Пример JSON для запроса
{
"title": "Api delivered webhooks",
"url": "https://mysite.org/webhook",
"kinds": ["api"],
"events": ["delivered"]
}
Пример запроса
curl -X POST https://app.smsgold.ru/v1/email/messages_webhooks \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id": 1,
"url": "https://mysite.org/webhook",
"events": [
"delivered"
],
"kinds": [
"api"
],
"status": "active",
"title": "Api delivered webhooks"
}
POST /email/messages_webhooks
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Название | Да |
url | Url для отправки webhooks | Да |
kinds | Типы сообщений | Да |
events | Список событий | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
url | Url для отправки webhooks |
kinds | Типы сообщений |
events | Список событий |
status | Статус |
Список вебхуков
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/messages_webhooks \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{
"total_count": 1,
"total_pages": 1,
"page_number": 1,
"page_size": 25,
"collection": [
{
"id": 1,
"url": "https://mysite.org/webhook",
"events": [
"delivered"
],
"kinds": [
"api"
],
"status": "active",
"title": "Api delivered webhooks"
}
]
}
GET /email/messages_webhooks
Ответ сервера
Ответ сервера содержит коллекцию вебхуков. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
url | Url для отправки webhooks |
kinds | Типы сообщений |
events | Список событий |
status | Статус |
Информация о вебхуке
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/messages_webhooks/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"id": 1,
"title": "Api delivered webhooks",
"url": "https://mysite.org/webhook",
"events": [
"delivered"
],
"kinds": [
"api"
],
"status": "active"
}
GET /email/messages_webhooks/:id
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
url | Url для отправки webhooks |
kinds | Типы сообщений |
events | Список событий |
status | Статус |
Изменение вебхука
Пример JSON для запроса
{
"events": ["opened"],
"kinds": ["campaign"],
"status": "inactive"
}
Пример запроса
curl -X PATCH https://app.smsgold.ru/v1/email/messages_webhooks/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{
"id": 1,
"title": "Api delivered webhooks",
"url": "https://mysite.org/webhook",
"events": [
"opened"
],
"kinds": [
"campaign"
],
"status": "inactive"
}
PATCH /email/messages_webhooks/:id
Параметры запроса
Атрибут | Описание |
---|---|
title | Название |
url | Url для отправки webhooks |
kinds | Типы сообщений |
events | Список событий |
status | Статус |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
url | Url для отправки webhooks |
kinds | Типы сообщений |
events | Список событий |
status | Статус |
Удаление вебхука
Пример запроса
curl -X DELETE https://app.smsgold.ru/v1/email/messages_webhooks/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"id": 1,
"title": "Api delivered webhooks",
"url": "https://mysite.org/webhook",
"events": [
"opened"
],
"kinds": [
"campaign"
],
"status": "inactive"
}
DELETE /email/messages_webhooks/:id
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
url | Url для отправки webhooks |
kinds | Типы сообщений |
events | Список событий |
status | Статус |
Запрос доступных типов сообщений
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/messages_webhooks/kinds \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"kinds": [
"campaign",
"campaign_transactional",
"campaign_workflow",
"api"
]
}
GET /email/messages_webhooks/kinds
Запрос доступных событий
Пример запроса
curl -X GET https://app.smsgold.ru/v1/email/messages_webhooks/events \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"events": [
"delivered",
"hard_bounced",
"skipped",
"opened",
"clicked",
"unsubscribed",
"complained",
"soft_bounced"
]
}
GET /email/messages_webhooks/events
SMTP
Подключение
Адрес: smtp.msndr.net
Для работы можно использовать следующие порты:
25
или587
— для соединения без шифрования или с использованием STARTTLS465
— в случае защищенного шифрованного соединения SSL/TLS
Аутентификация
Имя пользователя: email вашего аккаунта
Пароль: API ключ
Чтобы получить API ключ, авторизуйтесь в личном кабинете email рассылок. В разделе автоматизация перейдите во вкладку API и SMTP. Нажмите на "Параметры подключении и SMTP".
Пример SMTP сессии
$ telnet smtp.msndr.net 25
Trying 95.213.163.242...
Connected to smtp.msndr.net.
Escape character is '^]'.
220 smtp.msndr.net ESMTP service ready
ehlo sender
250-smtp.msndr.net
250-STARTTLS
250-AUTH PLAIN LOGIN
250-PIPELINING
250 8BITMIME
auth plain AHVzZXJAZXhhbXBsZS5vcmcAc29tZS1zdXBlci1wdXBlci1zZWNyZXQta2V5
235 authentication ok
mail from: mail@from.com
250 Ok
rcpt to: rcpt@to.com
250 Ok
rcpt to: rcpt1@to.com
250 Ok
data
354 End data with <CR><LF>.<CR><LF>
From: Mail From <mail@from.com>
Subject: Hello
X-Client-Id: 123
How are you doing?
.
250 Message accepted (sent messages <rcpt@to.com:1>,<rcpt1@to.com:2>)
quit
221 smtp.msndr.net closing connection
Connection closed by foreign host.
Обратите внимание, что ответ содержит строку с информацией об отправленных письмах.
Строка содержит адреса получателей и ID сообщений в формате <email:id>, объединенные запятой (см. пример выше). Вы можете использовать ID сообщений, чтобы запрашивать их статус через API или настроить отправку webhooks
К отправляемому сообщению можно добавлять собственные заголовки. Используйте заголовки формата X-My-Header: my value
.
Так, в указанном выше примере в результирующем сообщении будет присутствовать заголовок Client-Id: 123
.
Примеры PHP запросов
Получение списка групп получателей
<?php
$base_url = 'https://app.smsgold.ru/v1/email/';
$token = 'TOKEN';
$headers = array(
'Authorization: Bearer ' . $token,
'Content-Type: application/json'
);
$ch = curl_init($base_url . 'lists');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);
echo $response . "\n";
Получение параметров для группы получателей
<?php
$base_url = 'https://app.smsgold.ru/v1/email/';
$token = 'TOKEN';
$headers = array(
'Authorization: Bearer ' . $token,
'Content-Type: application/json'
);
$list_id = 'LIST ID';
$ch = curl_init($base_url . 'lists/' . $list_id . '/parameters');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);
echo $response . "\n";
Добавление получателя в группу
<?php
$base_url = 'https://app.smsgold.ru/v1/email/';
$token = 'TOKEN';
$headers = array(
'Authorization: Bearer ' . $token,
'Content-Type: application/json'
);
$list_id = 'LIST ID';
$parameter_id = 'PARAMETER ID';
$data = array(
'email' => 'foo@bar.com',
'values' => [
array(
'value' => 'Foo',
'parameter_id' => $parameter_id
)
]
);
$ch = curl_init($base_url . 'lists/' . $list_id . '/recipients');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
$response = curl_exec($ch);
curl_close($ch);
echo $response . "\n";
Импорт получателей в группу
<?php
$base_url = 'https://app.smsgold.ru/v1/email/';
$token = 'TOKEN';
$headers = array(
'Authorization: Bearer ' . $token,
'Content-Type: application/json'
);
$list_id = 'LIST ID';
$parameter_id = 'PARAMETER_ID';
$data = array(
'recipients' => [
array(
'email' => 'foo@bar.com',
'values' => [
array(
'value' => 'Foo',
'parameter_id' => $parameter_id
)
]
),
array(
'email' => 'bar@foo.com',
'values' => [
array(
'value' => 'Bar',
'parameter_id' => $parameter_id
)
]
)
]
);
$ch = curl_init($base_url . 'lists/' . $list_id . '/recipients/imports');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
$response = curl_exec($ch);
curl_close($ch);
echo $response . "\n";
Отправка одиночного сообщения
<?php
$base_url = 'https://app.smsgold.ru/v1/email/';
$token = 'TOKEN';
$headers = array(
'Authorization: Bearer ' . $token,
'Content-Type: application/json'
);
$from_email = 'SENDER';
$to = 'RECIPIENT';
$subject = 'Test';
$text = 'Hello from API';
$data = array(
'from_email' => $from_email,
'to' => $to,
'subject' => $subject,
'text' => $text
);
$ch = curl_init($base_url . 'messages');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
$response = curl_exec($ch);
curl_close($ch);
echo $response . "\n";
Отправка одиночного сообщения с вложениями
<?php
$base_url = 'https://app.smsgold.ru/v1/email/';
$token = 'TOKEN';
$headers = array(
'Authorization: Bearer ' . $token,
);
$from_email = 'SENDER';
$to = 'RECIPIENT';
$subject = 'Test';
$text = 'Hello from API';
$data = array(
'from_email' => $from_email,
'to' => $to,
'subject' => $subject,
'text' => $text,
'attachments[][0]' => curl_file_create('/path/to/file1'),
'attachments[][1]' => curl_file_create('/path/to/file2')
);
$ch = curl_init($base_url . 'messages');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$response = curl_exec($ch);
curl_close($ch);
echo $response . "\n";