API для сервисов email-рассылок: различия между версиями

Материал из Planfix
Перейти к: навигация, поиск
(Новая страница: «{{#seo: |title=API для интеграции с внешними сервисами электронной почты |titlemode=append |keywords=email, e-mail, рассылки, апи, api |description=API для интеграции с внешними сервисами электронной почты }} == Общие сведения об API == Данное API предназначено для владельцев сервисов рассылк...»)
 
Нет описания правки
Строка 1: Строка 1:
{{#seo: |title=API для интеграции с внешними сервисами электронной почты |titlemode=append |keywords=email, e-mail, рассылки, апи, api |description=API для интеграции с внешними сервисами электронной почты }}
== Общие сведения об API ==


== Общие сведения об API ==
Данное API предназначено для интеграции с внешними сервисами электронной почты и позволяет управлять списками рассылки и контактами через единый конечный пункт (например, https://yourserver.com/sendEmail.php), который принимает запросы в формате JSON.
Данное API предназначено для владельцев сервисов рассылки электронной почты и позволяет подключить ваш сервис отправки писем к нашей системе, если он отсутствует в списке доступных для интеграции.


После реализации интеграции вы можете настроить её в нашем интерфейсе, указав единый конечный адрес (например, https://yourserver.com/sendEmail.php), который будет принимать все запросы в формате JSON.
== Формат запроса ==
 
Запрос передаётся методом POST в формате JSON на адрес, указанный в настройках интеграции.
 
'''Пример запроса:'''
<pre>
{
  "action": "действие",
  "authToken": "ваш_токен_авторизации",
  "data": {
    // Данные, зависящие от действия
  }
}
</pre>
 
'''Параметры запроса:'''
{| class="wikitable" style="margin-top: 1em; width:100%"
!width="150"|Имя !!width="50%"|Описание !!width="150"|Тип/формат данных !!Примечание
|-
|action ||Действие, которое необходимо выполнить ||string ||
|-
|authToken ||Токен авторизации для доступа к API ||string ||
|-
|data ||Данные, зависящие от действия ||object ||
|-
|}
 
== Поддерживаемые действия ==
 
=== createList - Создание списка рассылки ===
 
'''Описание:''' Создает новый список рассылки с указанным именем.
 
'''Запрос:'''
<pre>
{
  "action": "createList",
  "authToken": "ваш_токен_авторизации",
  "data": {
    "listName": "Название списка"
  }
}
</pre>
 
'''Ответ (успех):'''
<pre>
{
  "success": true,
  "listId": "уникальный_идентификатор_списка"
}
</pre>


Взаимодействие производится по протоколу HTTPS. Система посылает запросы на указанный адрес с авторизацией через токен (см. поле authToken ниже).
'''Ответ (ошибка):'''
<pre>
{
  "error": "Описание ошибки"
}
</pre>


== Формат запроса ==
=== deleteList - Удаление списка рассылки ===
 
'''Описание:''' Удаляет список рассылки по его идентификатору.
 
'''Запрос:'''
<pre>
{
  "action": "deleteList",
  "authToken": "ваш_токен_авторизации",
  "data": {
    "listId": "идентификатор_списка"
  }
}
</pre>


Запрос передаётся методом POST в формате JSON (Content-Type: application/json).
'''Ответ (успех):'''
Пример общего формата запроса:
<pre>
{
  "success": true
}
</pre>


<pre> { "action": "действие", "authToken": "ваш_токен_авторизации", "data": { // Данные, зависящие от действия } } </pre>
'''Ответ (ошибка):'''
=== Поля запроса === {| class="wikitable" style="margin-top: 1em; width:100%" ! width="150" | Имя ! width="50%" | Описание ! width="150" | Пример |- | action || Тип выполняемого действия || createList |- | authToken || Токен авторизации для доступа к API || 12345abcde |- | data || Объект с дополнительными данными для указанного действия || {"listName": "Название списка"} |}
<pre>
{
  "error": "Описание ошибки"
}
</pre>


== Поддерживаемые действия ==
=== importContacts - Импорт контактов в список ===


=== createList — Создание списка рассылки === Пример запроса:
'''Описание:''' Импортирует контакты в указанный список рассылки.


<pre> { "action": "createList", "authToken": "ваш_токен_авторизации", "data": { "listName": "Название списка" } } </pre>
'''Запрос:'''
Ответ при успехе:
<pre>
{
  "action": "importContacts",
  "authToken": "ваш_токен_авторизации",
  "data": {
    "listId": "идентификатор_списка",
    "contacts": [
      {
        "id": 123,
        "email": "email@example.com",
        "firstName": "Имя",
        "lastName": "Фамилия"
      }
    ]
  }
}
</pre>


<pre> { "success": true, "listId": "уникальный_идентификатор_списка" } </pre>
'''Ответ (успех):'''
Ответ при ошибке:
<pre>
{
  "success": true
}
</pre>


<pre> { "error": "Описание ошибки" } </pre>
'''Ответ (ошибка):'''
=== deleteList — Удаление списка рассылки === Пример запроса:
<pre>
{
  "error": "Описание ошибки"
}
</pre>


<pre> { "action": "deleteList", "authToken": "ваш_токен_авторизации", "data": { "listId": "идентификатор_списка" } } </pre>
=== updateContact - Обновление контакта ===
Ответ при успехе:


<pre> { "success": true } </pre>
'''Описание:''' Обновляет контакт в списке рассылки. Поддерживает действия: добавление (add), обновление (update), удаление (delete).
=== importContacts — Импорт контактов в список === Пример запроса:


<pre> { "action": "importContacts", "authToken": "ваш_токен_авторизации", "data": { "listId": "идентификатор_списка", "contacts": [ { "id": 123, "email": "email@example.com", "firstName": "Имя", "lastName": "Фамилия" } ] } } </pre>
'''Запрос:'''
Ответ при успехе:
<pre>
{
  "action": "updateContact",
  "authToken": "ваш_токен_авторизации",
  "data": {
    "listId": "идентификатор_списка",
    "action": "add|update|delete",
    "contact": {
      "id": 123,
      "email": "email@example.com",
      "firstName": "Имя",
      "lastName": "Фамилия"
    },
    "oldEmail": "старый_email@example.com" // только для action=update
  }
}
</pre>


<pre> { "success": true } </pre>
'''Ответ (успех):'''
=== updateContact — Обновление контакта === Пример запроса:
<pre>
{
  "success": true
}
</pre>


<pre> { "action": "updateContact", "authToken": "ваш_токен_авторизации", "data": { "listId": "идентификатор_списка", "action": "add|update|delete", "contact": { "id": 123, "email": "email@example.com", "firstName": "Имя", "lastName": "Фамилия" }, "oldEmail": "старый_email@example.com" // только для action=update } } </pre>
'''Ответ (ошибка):'''
Ответ при успехе:
<pre>
{
  "error": "Описание ошибки"
}
</pre>


<pre> { "success": true } </pre>
== Примечания ==
== Примечания ==
* Все запросы должны возвращать ответ в формате JSON.
* В случае ошибки всегда должно присутствовать поле "error" с описанием ошибки.
* В случае успеха всегда должно присутствовать поле "success": true.
* Авторизация происходит через поле authToken в каждом запросе.
* Все текстовые поля должны быть в кодировке UTF-8.


Все запросы должны возвращать ответ в формате JSON.
== Перейти ==
В случае ошибки всегда должно присутствовать поле "error" с описанием ошибки.
*[[Разработчикам: API]]
В случае успеха всегда должно присутствовать поле "success": true.
Авторизация происходит через поле authToken в каждом запросе.
Все текстовые поля должны быть в кодировке UTF-8.

Версия от 10:08, 1 марта 2025

Общие сведения об API

Данное API предназначено для интеграции с внешними сервисами электронной почты и позволяет управлять списками рассылки и контактами через единый конечный пункт (например, https://yourserver.com/sendEmail.php), который принимает запросы в формате JSON.

Формат запроса

Запрос передаётся методом POST в формате JSON на адрес, указанный в настройках интеграции.

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

{
  "action": "действие",
  "authToken": "ваш_токен_авторизации",
  "data": {
    // Данные, зависящие от действия
  }
}

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

Имя Описание Тип/формат данных Примечание
action Действие, которое необходимо выполнить string
authToken Токен авторизации для доступа к API string
data Данные, зависящие от действия object

Поддерживаемые действия

createList - Создание списка рассылки

Описание: Создает новый список рассылки с указанным именем.

Запрос: 

{
  "action": "createList",
  "authToken": "ваш_токен_авторизации",
  "data": {
    "listName": "Название списка"
  }
}

Ответ (успех): 

{
  "success": true,
  "listId": "уникальный_идентификатор_списка"
}

Ответ (ошибка): 

{
  "error": "Описание ошибки"
}

deleteList - Удаление списка рассылки

Описание: Удаляет список рассылки по его идентификатору.

Запрос: 

{
  "action": "deleteList",
  "authToken": "ваш_токен_авторизации",
  "data": {
    "listId": "идентификатор_списка"
  }
}

Ответ (успех): 

{
  "success": true
}

Ответ (ошибка): 

{
  "error": "Описание ошибки"
}

importContacts - Импорт контактов в список

Описание: Импортирует контакты в указанный список рассылки.

Запрос: 

{
  "action": "importContacts",
  "authToken": "ваш_токен_авторизации",
  "data": {
    "listId": "идентификатор_списка",
    "contacts": [
      {
        "id": 123,
        "email": "email@example.com",
        "firstName": "Имя",
        "lastName": "Фамилия"
      }
    ]
  }
}

Ответ (успех): 

{
  "success": true
}

Ответ (ошибка): 

{
  "error": "Описание ошибки"
}

updateContact - Обновление контакта

Описание: Обновляет контакт в списке рассылки. Поддерживает действия: добавление (add), обновление (update), удаление (delete).

Запрос: 

{
  "action": "updateContact",
  "authToken": "ваш_токен_авторизации",
  "data": {
    "listId": "идентификатор_списка",
    "action": "add|update|delete",
    "contact": {
      "id": 123,
      "email": "email@example.com",
      "firstName": "Имя",
      "lastName": "Фамилия"
    },
    "oldEmail": "старый_email@example.com" // только для action=update
  }
}

Ответ (успех): 

{
  "success": true
}

Ответ (ошибка): 

{
  "error": "Описание ошибки"
}

Примечания

  • Все запросы должны возвращать ответ в формате JSON.
  • В случае ошибки всегда должно присутствовать поле "error" с описанием ошибки.
  • В случае успеха всегда должно присутствовать поле "success": true.
  • Авторизация происходит через поле authToken в каждом запросе.
  • Все текстовые поля должны быть в кодировке UTF-8.

Перейти

Источник — http://planfix.com/ru/help/index.php?title=API_для_сервисов_email-рассылок&oldid=47730