Перед использованием API необходимо зайти в окно Настройки->Настройки API, задать параметры и включить API сервер:

 

apisettings

 

Настройка API сервера

 

В первую очередь выберите протоколы, через которые будет взаимодействие с API. Поддерживаются два варианта HTTP и защищенный HTTPS. Протокол HTTPS обеспечивает шифрование данных между клиентом и API сервером, однако из-за больших накладных расходов работает медленнее чем HTTP. Вы можете включить один или сразу оба протокола использовать любой на ваш выбор. Так же нужно указать номер порта, который будет слушать API сервер. По умолчанию используются стандартные порты - 80 для HTTP и 443 для HTTPS. Однако, если у вас уже установлено какое-то ПО (например web сервер), которое слушает этот же порт - при запуске API сервера вы получите ошибку, что порт уже занят. В это случае вы можете задать любой другой свободный порт и заново запустить сервер.

 

Если вы хотите использовать защищенный HTTPS протокол вы можете установить SSL сертификат из .pem или .pfx файла, нажав кнопку Установить SSL сертификат. По умолчанию используется само-подписанный сертификат, который обеспечивает работу HTTPS сервера и шифрование обмена данными, но при обращении к API URL из браузера будет выдаваться предупреждение, что само-подписанный сертификат не может быть проверен браузером. Если этот момент является для вас критичным - вы можете использовать настоящий (платный) SSL сертификат. AMS использует сертификат в формате PKCS#12 (*.pfx) и сохраняет его в папку %appdata%\AMSEnt\Data\ApiServerSslCerts\Server.pfx

 

При первом запуске программы генерируется новый уникальный Ключ API, которые необходимо использовать при вызове команд API. При желании вы можете Создать новый ключ с помощью соответствующей кнопки.

 

После того, как все настройки были заданы нажмите кнопку Включить API сервер.

 

Так же, в некоторых случаях, вам может потребоваться добавить AMS в исключения файрвола и, возможно, изменить настройки вашего роутера если вы хотите что API сервер AMS был доступен из вне (из интернета).

 

API URL, формат данных, авторизация

 

Для отправки команд API используйте URL http://127.0.0.1/api/v1 или https://127.0.0.1/api/v1 где 127.0.0.1 это IP адрес компьютера (сервера) где установлен AMS. Content-Type для POST запроса должен быть application/json.

 

API использует данные в формате JSON по спецификации JSON-RPC 2.0, подробная информация о спецификации здесь: https://www.jsonrpc.org/specification

 

Каждая команда API должна содержать обязательный параметр apiKey, в котором необходимо передавать ключ доступа к API, который вы можете взять в окне настроек API (см. скриншот выше). Ответы API сервера так же соответствуют спецификации JSON-RPC 2.0.

 

Описание команд API

 
getSenderAccounts - получить список Учетных записей отправителя.

getMailingLists - получить перечень Списков рассылки.

getMessages - получить список Писем.

getDeliveryPresets - получить список Профилей отправки

 

getMailings - получить список созданных Рассылок

getMailing - получить детальную информацию о Рассылке

addMailing - создать новую Рассылку.

editMailing - редактировать параметры Рассылки

deleteMailing - удалить Рассылку

startMailing - запустить Рассылку

stopMailing - остановить Рассылку.

 

postSendingJob                        - отправить задание на отправку в очередь транзакционной рассылки.

 

Команда: getSenderAccounts

 

Выдает список доступных Учетных записей отправителя.

 

Описание параметров

Пример вызова

apiKey - ключ доступа к API

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"getSenderAccounts",

  "params": {"apiKey": "5EB20EC3-F672-4A26-8F65-9FC162ED4EAB"},

  "id":"1"

}'

 

Примечание: в этом и последующем примерах вызов функции API приводится в общепринятом виде для команды curl. Чистое тело запроса, без параметров curl будет выглядеть так:

 

{"jsonrpc":"2.0", "method":"getSenderAccounts", "params": {"apiKey": "5EB20EC3-F672-4A26-8F65-9FC162ED4EAB"},id":"1"}

 

 

Описание параметров, примечания

Пример ответа

Ответ команды содержит массив со списком доступных учетных записей отправителя:

 

apiaccslist

 

Обратите внимание на параметр id, который передается в ответе. Это уникальный идентификатор Учетной записи отправителя. Он может использоваться в дальнейшем в командах addMailing и editMailing для указания какая Учетная запись должна использоваться для создаваемой/редактируемой рассылки.

 

accountName - имя учетной записи

 

senderName - имя отправителя (From:)

 

senderEmail - email адрес отправителя (From:)

 

replyToEmail - reply-to: адрес.

 

organization - организация отправителя.

 

espDomain - esp домен для подписывания письма второй DKIM подписью.

{

 "jsonrpc":"2.0",

 "result":[

   {

     "id":1,

     "accountName":"Example account 1",

     "senderName":"Bill Gates",

     "senderEmail":"bill@microsoft.com",

     "replyToEmail":"reply@microsoft.com",

     "organization":"Microsoft",

     "espDomain":"domain.com"

   },

   {

     "id":2,

     "accountName":"Example account 2",

     "senderName":"Jeff Bezos",

     "senderEmail":"jeff@amazon.com",

     "replyToEmail":"reply@amazon.com",

     "organization":"Amazon",

     "espDomain":"somedomain.com"

   }

 ],

 "id":1

}

 

 

Команда: getMailingLists

 

Выдает список доступных списков рассылки.

 

Описание параметров

Пример вызова

apiKey - ключ доступа к API

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"getMailingLists",

  "params": {"apiKey": "5EB20EC3-F672-4A26-8F65-9FC162ED4EAB"},

  "id":"1"

}'

Описание параметров, примечания

Пример ответа

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

apimlists

 

Обратите внимание на параметр id, который передается в ответе. Это уникальный идентификатор Списка рассылки. Он может использоваться в дальнейшем в командах addMailing и editMailing для указания какой Список рассылки должен использоваться для создаваемой/редактируемой рассылки.

 

parentID - ID родительского списка (с помощью этого поля строится древовидная структура списков рассылки).

 

listName - имя списка рассылки.

 

Size - число адресов в списке рассыкли.

 

lastMailing - дата последнего запуска любой рассылки по этому списку.

{

 "jsonrpc":"2.0",

 "result":[

   {

     "id":102,

     "parentID":-1,

     "listName":"Mailing Lists",

     "size":0,

     "lastMailing":""

   },

   {

     "id":261,

     "parentID":102,

     "listName":"Example mail list",

     "size":2,

     "lastMailing":"14.09.2021"

   },

   {

     "id":263,

     "parentID":261,

     "listName":"sub list 1",

     "size":2,

     "lastMailing":""

   },

   {

     "id":264,

     "parentID":261,

     "listName":"sub list 2",

     "size":0,

     "lastMailing":""

   }

 ],

 "id":1

}

 

 

Команда: getMessages

 

Выдает список доступных писем.

 

Описание параметров

Пример вызова

apiKey - ключ доступа к API

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"getMessages",

  "params": {"apiKey": "5EB20EC3-F672-4A26-8F65-9FC162ED4EAB"},

  "id":"1"

}'

Описание параметров, примечания

Пример ответа

Ответ команды содержит массив с доступными письмами:

 

apimsglist

 

Обратите внимание на параметр id, который передается в ответе. Это уникальный идентификатор Письма. Он может использоваться в дальнейшем в командах addMailing и editMailing для указания какое Письмо должно использоваться для создаваемой/редактируемой рассылки.

 

subject - тема письма.

 

messageName - имя письма.

 

messageType - тип письма. Возможные значения html или plainText.

 

openTracking - для письма разрешен сбор статистики по открытым письмам.

 

clicksTracking - для письма разрешен сбор статистики по кликам на ссылки.

 

{

 "jsonrpc":"2.0",

 "result":[

   {

     "id":1,

     "subject":"My message",

     "messageName":"example message",

     "messageType":"html",

     "openTracking":true,

     "clicksTracking":true

   },

   {

     "id":2,

     "subject":"my second message",

     "messageName":"another message",

     "messageType":"plainText",

     "openTracking":false,

     "clicksTracking":false

   }

 ],

 "id":1

}

 

 

Команда: getDeliveryPresets

 

Выдает список доступных профилей отправки.

 

Описание параметров

Пример вызова

apiKey - ключ доступа к API

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"getDeliveryPresets",

  "params": {"apiKey": "5EB20EC3-F672-4A26-8F65-9FC162ED4EAB"},

  "id":"1"

}'

Описание параметров, примечания

Пример ответа

Ответ команды содержит массив с доступными письмами:

 

apipresets

 

Обратите внимание на параметр id, который передается в ответе. Это уникальный идентификатор Профиля отправки. Он может использоваться в дальнейшем в командах addMailing и editMailing для указания какой Профиль должен использоваться для создаваемой/редактируемой рассылки.

 

name - имя профиля отправки.

 

sendingMethod - метод отправки писем, возможные значения: to, cc, bcc, personalCopy

 

deliveryMode - режим доставки профиля. Возможные значения: relaysOnly (только smtp релеи), relaysAndBuiltInServerOnErrors (smtp релеи, а при ошибках встроенный smtp сервер), builtInServerAndRelaysOnErrors (встроенный smtp сервер, а при ошибках smtp релеи), builtInServerOnly (только встроенный smtp сервер).

 

proxyUsed - используются ли прокси для рассылки.

 

sendingThreads - число потоков отправки, которые создаст данный Профиль.

 

{

 "jsonrpc":"2.0",

 "result":[

   {

     "id":1,

     "name":"Example preset",

     "sendingMethod":"personalCopy",

     "deliveryMode":"relaysOnly",

     "proxyUsed":false,

     "sendingThreads":50

   },

   {

     "id":2,

     "name":"Another preset",

     "sendingMethod":"personalCopy",

     "deliveryMode":"builtInServerOnly",

     "proxyUsed":true,

     "sendingThreads":30

   }

 ],

 "id":1

}

 

 

Команда: getMailings

 

Выдает список имеющихся рассылок, а так же их состояние и прогресс.

 

 

Описание параметров

Пример вызова

apiKey - ключ доступа к API

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"getMailings",

  "params": {"apiKey": "5EB20EC3-F672-4A26-8F65-9FC162ED4EAB"},

  "id":"1"

}'

Описание параметров, примечания

Пример ответа

Ответ команды содержит массив с перечнем имеющихся рассылок, их состоянием и прогрессом:

 

apimailings   apimailingstate

 

 

Обратите внимание на параметр id, который передается в ответе. Это уникальный идентификатор Рассылки. Он может использоваться в дальнейшем в командах startMailing и stopMailing для запуска/остановки нужных рассылок.

 

name - имя рассылки.

 

type - информация о типе рассылки. Возможные значения: mailing (обычная рассылка), validation (валидация базы), transactional (транзакционная рассылка).

 

state - состояние рассылки. Возможные значения: idle (остановлена), working (работает), stopping (останавливается).

 

createDate - дата создания рассылки

 

lastStartDate - дата/время последнего запуска рассылки

 

approxSpeed - средняя скорость отправки.

 

lastStopByPostmaster - последняя остановка рассылки была через интеграцию с postmaster.mail.ru (письма начали идти в спам).

 

enableCustomExcludeList - включен ли для рассылки персональный список исключений.

 

customExcludeListID - ID списка рассылки, который используется в качестве персонального Списка Исключений для этой рассылки.

 

progressInfo - информация о текущем прогрессе рассылки и числе отправленных, не отправленных и т.д. письмах. Обратите внимание, что объект progressInfo может содержать разные поля в зависимости от типа рассылки. Например, у транзакционных рассылок нет прогресса и поля percentDone, а у валидации базы нет числа отправленных писем и т.д. В примере ответа справа вы можете увидеть все варианты progressInfo в зависимости от типа рассылки.

 

 

{

 "jsonrpc":"2.0",

 "result":[

   {

     "id":73,

     "name":"Example mailing",

     "type":"mailing",

     "state":"idle",

     "createDate":"2021-09-13",

     "lastStartDate":"2021-09-13T20:10:46",

     "approxSpeed":"1460\/min",

     "lastStopByPostmaster":false,

     "enableCustomExcludeList":true,

     "customExcludeListID":461,

     "progressInfo":{

       "percentDone":0,

       "total":26243,

       "sent":10432,

       "notSent":653,

       "bad":47,

       "refused":0,

       "excluded":0,

       "opened":826,

       "clicks":611

     }

   },

   {

     "id":75,

     "name":"Example mail list validation",

     "type":"validation",

     "state":"idle",

     "createDate":"2021-09-22",

     "lastStartDate":"",

     "approxSpeed":"688\/min",

     "lastStopByPostmaster":false,

     "enableCustomExcludeList":false,

     "customExcludeListID":0,

     "progressInfo":{

       "percentDone":100,

       "total":11266,

       "good":8960,

       "bad":1222,

       "undetermined":1084,

       "excluded":0

     }

   },

   {

     "id":76,

     "name":"Example transactional mailing",

     "type":"transactional",

     "state":"idle",

     "createDate":"2021-09-26",

     "lastStartDate":"",

     "approxSpeed":"0\/min",

     "lastStopByPostmaster":false,

     "enableCustomExcludeList":false,

     "customExcludeListID":0,

     "progressInfo":{

       "jobsQueued":0,

       "contactsQueued":0,

       "total":9142,

       "sent":5339,

       "notSent":121,

       "bad":0,

       "refused":0,

       "excluded":2841,

       "opened":916,

       "clicks":1265

     }

   }

 ],

 "id":1

}

 

 

Команда: getMailing

 

Выдает подробную информацию о рассылке и ее настройках.

 

 

Описание параметров

Пример вызова

apiKey - ключ доступа к API

 

id - ID рассылки, информация о которой запрашивается.

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"getMailing",

  "params": {"apiKey": "5EB20EC3-F672-4A26-8F65-9FC162ED4EAB","ID":73},

  "id":"1"

}'

Описание параметров, примечания

Пример ответа

Ответ команды содержит подробную информацию о рассылке: ее имени, прогрессе и настройках. Ответ команды содержит информацию из этих окон и полей AMS:

 

apinewmailing   apimailingstate apimailingsettings

 

Поля: name, type, state, createDate, lastStartDate, approxSpeed, lastStopByPostmaster, enableCustomExcludeList, customExcludeListID, progressInfo - содержат базовую информацию о рассылке, и содержат ту же информацию, что и вызов команды getMailings.

 

settings - объект с настройками рассылки:

 

senderAccount - объект и информацией об учетной записи отправителя, выбранной для данной рассылки.

id - id учетной записи.

name - имя учетной записи.

 

mailList - объект с информацией о списке рассылки, выбранной для данной рассылки.

id - id списка рассылки.

name - имя списка рассылки.

 

message - объект с информацией о письме, выбранном для данной рассылки.

id - id письма.

subject - тема письма

name - имя письма

 

deliveryPreset - объект с информацией о профиле отправки, выбранном для данной рассылки.

id - id профиля отправки.

name - имя профиля отправки.

 

controlEmailsSending - объект с настройками отправки контрольных писем.

enabled - отправка контрольных писем разрешена
 

controlEmails - массив с адресами, куда будут отправляться контрольные письма.
 

sendingIntervalMode - режим отправки контрольных писем. Возможные варианты: byMessagesNumber (отправлять письма на контрольные адреса после отправки числа обычных писем), byMailingProgress (отправлять письма на контрольные адреса через заданный % прогресса рассылки).
 
sendingIntervalValue - в зависимости от значения параметра sendingIntervalMode - число писем или % прогресса, после которого должна выполняться отправка на контрольные адреса.

 

postmasterIntegration - объект с настройками интеграции с https://postmaster.mail.ru

enabled - интеграция разрешена.

 

postmasterAccountID - ID аккаунта интеграции с постмастером. На данный момент нет команды API для их получения. Список аккаунтов и их ID вы можете посмотреть в окне Настройки->postmaster.mail.ru

 

postmasterDomains - массив с доменами, информация о доставке с которых будет запрашиваться у postmaster.mail.ru для этой рассылки.

 

enableMailingAutoStop - разрешить автоматическую остановку рассылки если postmaster.mail.ru дал информацию о том, что письма стали уходить в спам или возможно спам.

 

autoStopPostmasterData - какие данные postmaster.mail.ru будут анализироваться для остановки рассылки. Возможные значения: spam (число или процент писем, попавших в Спам), probablySpam (число или процент писем, попавших в Возможно спам), spamOrProbablySpam (число или процент писем, попавших в Спам ИЛИ в Возможно спам).

 

autoStopValueType - определяет тип информации о письмах, поправших в спам или возможно спам, которые будут анализироваться для остановки рассылки. Возможные значения: spamMsgNumber (анализируется число писем, попавших в спам или возможно спам), spamPercent (анализируется процент писем, попавших в спам или возможно спам).

 

autoStopValue - в зависимости от содержимого параметра autoStopValueType - число или процент писем, попавших в спам или возможно спам, при достижении которого рассылка будет автоматически остановлена.

 

disableSendingLog - запись логов рассылки отключена для экономии места на диске.

{

 "jsonrpc":"2.0",

 "result":{

   "id":73,

   "name":"Example mailing",

   "type":"mailing",

   "state":"idle",

   "createDate":"2003-11-13",

   "lastStartDate":"2007-12-14T20:10:46",

   "approxSpeed":"0\/min",

   "lastStopByPostmaster":false,

   "enableCustomExcludeList":true,

   "customExcludeListID":461,

   "progressInfo":{

     "percentDone":0,

     "total":2,

     "sent":0,

     "notSent":0,

     "bad":0,

     "refused":0,

     "excluded":0,

     "opened":0,

     "clicks":0

   },

   "settings":{

     "senderAccount":{

       "id":17,

       "name":"Example account 1"

     },

     "mailList":{

       "id":261,

       "name":"Example mail list"

     },

     "message":{

       "id":1,

       "subject":"My message",

       "name":"example message"

     },

     "deliveryPreset":{

       "id":18,

       "name":"Example preset"

     },

     "controlEmailsSending":{

       "enabled":true,

       "controlEmails":[

         "seed1@hotmail.com",

         "seed2@gmail.com"

       ],

       "sendingIntervalMode":"byMessagesNumber",

       "sendingIntervalValue":1000

     },

     "postmasterIntegration":{

       "enabled":true,

       "postmasterAccountID":4,

       "postmasterDomains":[

         "domain1.ru",

         "domain2.com"

       ],

       "enableMailingAutoStop":true,

       "autoStopPostmasterData":"spamOrProbablySpam",

       "autoStopValueType":"spamMsgNumber",

       "autoStopValue":10

     },

     "disableSendingLog":false

   }

 },

 "id":1

}



 

 

Команда: addMailing

 

Создает новую рассылку.

 

Описание параметров

Пример вызова

С помощью команды addMailing вы можете создать новую рассылку и задать ее настройки. Команда позволяет задать настройки из этих окон AMS:

 

apinewmailing     apimailingsettings

 

apiKey - ключ доступа к API

 

name - имя создаваемой рассылки. Обязательный параметр.

 

type - тип создаваемой рассылки. Возможные значения: mailing (обычная рассылка), validation (валидация базы), transactional (транзакционная рассылка). Обязательный параметр.

 

enableCustomExcludeList - включить для рассылки персональный список исключений.

 

customExcludeListID - ID списка рассылки, который используется в качестве персонального Списка Исключений для этой рассылки.

 

settings - настройки создаваемой рассылки:

 

senderAccount - объект и информацией об учетной записи отправителя, выбранной для данной рассылки.

id - id учетной записи.

 

mailList - объект с информацией о списке рассылки, выбранной для данной рассылки.

id - id списка рассылки.

 

message - объект с информацией о письме, выбранном для данной рассылки.

id - id письма.

 

deliveryPreset - объект с информацией о профиле отправки, выбранном для данной рассылки.

id - id профиля отправки.

 

controlEmailsSending - объект с настройками отправки контрольных писем. Не обязательный параметр. Если отсутствует - отправка контрольных писем выключена.

enabled - отправка контрольных писем разрешена
 

controlEmails - массив с адресами, куда будут отправляться контрольные письма.
 

sendingIntervalMode - режим отправки контрольных писем. Возможные варианты: byMessagesNumber (отправлять письма на контрольные адреса после отправки числа обычных писем), byMailingProgress (отправлять письма на контрольные адреса через заданный % прогресса рассылки).
 
sendingIntervalValue - в зависимости от значения параметра sendingIntervalMode - число писем или % прогресса, после которого должна выполняться отправка на контрольные адреса.

 

postmasterIntegration - объект с настройками интеграции с https://postmaster.mail.ru. Не обязательный параметр. Если отсутствует - интеграция выключена.

enabled - интеграция разрешена.

 

postmasterAccountID - ID аккаунта интеграции с постмастером. На данный момент нет команды API для их получения. Список аккаунтов и их ID вы можете посмотреть в окне Настройки->postmaster.mail.ru

 

postmasterDomains - массив с доменами, информация о доставке с которых будет запрашиваться у postmaster.mail.ru для этой рассылки.

 

enableMailingAutoStop - разрешить автоматическую остановку рассылки если postmaster.mail.ru дал информацию о том, что письма стали уходить в спам или возможно спам.

 

autoStopPostmasterData - какие данные postmaster.mail.ru будут анализироваться для остановки рассылки. Возможные значения: spam (число или процент писем, попавших в Спам), probablySpam (число или процент писем, попавших в Возможно спам), spamOrProbablySpam (число или процент писем, попавших в Спам ИЛИ в Возможно спам).

 

autoStopValueType - определяет тип информации о письмах, поправших в спам или возможно спам, которые будут анализироваться для остановки рассылки. Возможные значения: spamMsgNumber (анализируется число писем, попавших в спам или возможно спам), spamPercent (анализируется процент писем, попавших в спам или возможно спам).

 

autoStopValue - в зависимости от содержимого параметра autoStopValueType - число или процент писем, попавших в спам или возможно спам, при достижении которого рассылка будет автоматически остановлена.

 

disableSendingLog - запись логов рассылки отключена для экономии места на диске. Не обязательный параметр. По умолчанию запись логов включена.

 

Примечание: вы можете использовать выдачу команды getMailing если нужно быстро создать новую рассылку со схожими настройками. Т.е. вы можете сначала отправить команду getMailing, получить информацию о нужной рассылке, после чего изменить некоторые настройки (например имя или id списка рассылки) и отправить модифицированный json объект в качестве параметров для функции addMailing. Таким образом вам не нужно будет формировать параметры создания с нуля.

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"addMailing",

 "params":{

   "apiKey":"5EB20EC3-F672-4A26-8F65-9FC162ED4EAB",

   "name":"Example mailing 1",

   "type":"mailing",

   "enableCustomExcludeList":true,

   "customExcludeListID":461,

   "settings":{

     "senderAccount":{

       "id":22

     },

     "mailList":{

       "id":263

     },

     "message":{

       "id":189

     },

     "deliveryPreset":{

       "id":1026

     },

     "controlEmails":[

         "seed1@hotmail.com",

         "seed2@gmail.com"

       ],

       "sendingIntervalMode":"byMessagesNumber",

       "sendingIntervalValue":1000

     },

     "postmasterIntegration":{

       "enabled":true,

       "postmasterAccountID":4,

       "postmasterDomains":[

         "mydomain.com"

       ],

       "enableMailingAutoStop":true,

       "autoStopPostmasterData":"spam",

       "autoStopValueType":"spamPercent",

       "autoStopValue":0.1

     },

     "disableSendingLog":false

   }

 },

 "id":"1"

}'

Описание параметров, примечания

Пример ответа

newResourceID - ID созданной рассылки.

{

 "jsonrpc":"2.0",

 "result":{

   "newResourceID":77

 },

 "id":1

}

 

 

Команда: editMailing

 

Изменить настройки рассылки.

 

Описание параметров

Пример вызова

Команда editMailing работает практически с тем же набором параметров, что и команда addMailing, требуется только один дополнительный параметр:

 

id - ID рассылки, настройки которой нужно изменить. Список ID имеющихся рассылок можно получить с помощью команды getMailings

 

apiKey - ключ доступа к API

 

Все остальные параметры аналогичны функции addMailing

 

Примечание: вы можете использовать выдачу команды getMailing как источник данных для команды editMailing. Т.е. вы можете сначала отправить команду getMailing, получить информацию о нужной рассылке, после чего изменить некоторые настройки (например имя или id списка рассылки) и отправить модифицированный json объект в качестве параметров для функции editMailing. Таким образом вам не нужно будет формировать объект с параметрами рассылки с нуля.

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"editMailing",

 "params":{

   "apiKey":"5EB20EC3-F672-4A26-8F65-9FC162ED4EAB",

   "id":77,

   "name":"Example mailing 1",

   "type":"mailing",

   "enableCustomExcludeList":true,

   "customExcludeListID":461,

   "settings":{

     "senderAccount":{

       "id":22

     },

     "mailList":{

       "id":263

     },

     "message":{

       "id":189

     },

     "deliveryPreset":{

       "id":1026

     },

     "controlEmails":[

         "seed1@hotmail.com",

         "seed2@gmail.com"

       ],

       "sendingIntervalMode":"byMessagesNumber",

       "sendingIntervalValue":1000

     },

     "postmasterIntegration":{

       "enabled":true,

       "postmasterAccountID":4,

       "postmasterDomains":[

         "mydomain.com"

       ],

       "enableMailingAutoStop":true,

       "autoStopPostmasterData":"spam",

       "autoStopValueType":"spamPercent",

       "autoStopValue":0.1

     },

     "disableSendingLog":false

   }

 },

 "id":"1"

}'

Описание параметров, примечания

Пример ответа

В случае успеха строка "ОК" или ошибка.

{

 "jsonrpc":"2.0",

 "result":"OK",

 "id":1

}

 

 

Команда: deleteMailing

 

Удалить рассылку.

 

Описание параметров

Пример вызова

apiKey - ключ доступа к API

 

id - ID рассылки, которую нужно удалить. Список ID имеющихся рассылок можно получить с помощью команды getMailings

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"deleteMailing",

  "params": {"apiKey": "5EB20EC3-F672-4A26-8F65-9FC162ED4EAB","id":77},

  "id":"1"

}'

Описание параметров, примечания

Пример ответа

В случае успеха строка "ОК" или ошибка.

{

 "jsonrpc":"2.0",

 "result":"OK",

 "id":1

}

 

Команда: startMailing

 

Запустить рассылку.

 

Описание параметров

Пример вызова

Данная команда, фактически, повторяет логику работы кнопки запуска рассылки AMS:

 

apistartmailing

 

apiKey - ключ доступа к API

 

id - ID рассылки, которую нужно запустить. Список ID имеющихся рассылок можно получить с помощью команды getMailings

 

startMode - режим запуска рассылки. Обязательный параметр. Возможные значения:

continue - запустить или продолжить рассылку с места остановки.

resendNotSent - запустить в режиме переотправки на не отправленные

resendBad - запустить в режиме переотправки на адреса, которые были определены как плохие.

resendRefused - запустить в режиме переотправки на не принятые адреса.

restart - перезапустить рассылку с начала (при этом текущий прогресс и результаты будут перезаписаны.

 

stopMode - опциональный параметр, в котором можно указать как долго должна работать рассылка. Возможные значения: LimitWorkMinutes - остановить рассылку по прошествии числа минут, LimitProcessedMessages - остановить рассылку после обработки числа писем (под обработкой понимается число писем, которые были помещены в очередь рассылки, для которых была сделана попытка отправки, при этом результат отправки не принимается во внимание).

stopValue - в зависимости от значения параметра stopMode - число минут или число обработанных писем после которых рассылка будет остановлена.

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"startMailing",

  "params": {"apiKey": "5EB20EC3-F672-4A26-8F65-9FC162ED4EAB", "id":77, "startMode":"continue","stopMode":"LimitWorkMinutes","stopValue":30},

  "id":"1"

}'

Описание параметров, примечания

Пример ответа

В случае успеха строка "ОК" или ошибка.

{

 "jsonrpc":"2.0",

 "result":"OK",

 "id":1

}

 

Команда: stopMailing

 

Остановить рассылку.

 

Описание параметров

Пример вызова

apiKey - ключ доступа к API

 

id - ID рассылки, которую нужно остановить. Список ID имеющихся рассылок можно получить с помощью команды getMailings

 

Вы можете остановить только рассылки, которые запущенны на данный момент. У запущенный рассылок параметр state равен working

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"stopMailing",

  "params": {"apiKey": 5EB20EC3-F672-4A26-8F65-9FC162ED4EAB", "id":77, "startMode":"continue"},

  "id":"1"

}'

Описание параметров, примечания

 

Пример ответа

В случае успеха строка "ОК" или ошибка.

{

 "jsonrpc":"2.0",

 "result":"OK",

 "id":1

}

 

Команда: postSendingJob

 

Добавить задание в очередь отправки транзакционной рассылки.

 

Транзакционная рассылка - это особый тип рассылки, для которой нельзя выбрать список получателей и которая отправляет письма исключительно на перечни контактов, переданные вместе с командой API postSendingJob из вашего ПО. Транзакционные рассылки запускаются автоматически при старте AMS  и ожидают команд на отправку от сервера API. У транзакционной рассылки нет прогресса работы т.к. заранее не известно сколько получателей придет вместе с командами postSendingJob. По умолчанию отправляется письмо, выбранное для транзакционной рассылки на главном окне AMS. Однако, если вместе с командой передается параметр customMessage - содержимое письма, переданное в этом параметре переопределяет содержимое письма, выбранного для рассылки на главном окне AMS.

 

Описание параметров

Пример вызова

apiKey - ключ доступа к API

 

jobID - опциональный параметр для вашего идентификатора задания. Т.е. вы можете задавать разные jobID для разных типов заданий и потом вы сможете использовать из в выборках с join по этому полю в результатах рассылок чтобы посмотреть результаты по заданиям, относящихся к некоторому классу, или для конкретного задания (если вы будете назначать уникальные jobID). Макс. длинна значения – 38 символов (хватит для GUID).

 

mailingID - ID транзакционной рассылки, в чью очередь отправки будет добавлено данное задание. Список ID имеющихся рассылок можно получить с помощью команды getMailings. У транзакционных рассылок поле type равно transactional

 

contacts - массив с получателями, куда нужно отправить письмо. При формировании элементов массива придерживайтесь следующих правил:

 

Каждый элемент массива должен содержать обязательные поля ID, Email, FullName, при этом поле Email не должно быть пустым.

 

В поле ID вы можете передать уникальный ID контакта из вашей БД (чтобы потом была возможность сделать выборку по результатам рассылок с join по ID контакта). Поле ID может содержать пустое значение. Макс. длинна ID – 38 символов (хватит для GUID).

 

В поле FullName вы можете передать имя получателя (которое будет подставлено в поле To: отправляемых писем). Значения поля может быть пустым. Макс длинна 100 символов.

 

После обязательных полей ID, Email, FullName – вы можете передать любое количество других полей и их значений. Не должно быть полей с одинаковыми именами. Все поля можно использовать в теле письма в подстановках через макросы [%%FИмяПоля%%]. Желательно чтобы имена полей состояли только из английских букв и цифр.

 

Все элементы массива contacts должны содержать одинаковый набор полей в одинаковой последовательности ! Т.е. не может быть, что у одного контакта есть поле City, а у другого нет (может быть пустое значение поля, но само поле должно быть). Вы можете менять набор полей от задания к заданию, но внутри задания поля должны быть одинаковыми, в одинаковой последовательности.

 

Значения всех полей контакта должны передаваться в виде строк (например, передавать не число 10, а строку “10”)
 

Если массив contacts содержит более одного элемента – метод их отправки будет определяться настройкой профиля отправки. Например, если режим Personal copy – это будет отправка по одному письму, если BCC – то в пакетном режиме (одно тело письма – много получателей). При этом если настройка размера BCC в профиле не соответствует числу контактов в массиве contacts – софт это правильно обработает, разобьет задание на подзадания и отправит корректным образом, не допуская чтобы в поле To: одного письма находились адреса из разных команд postSendingJob.

 

customMessage - объект, в котором вы можете передать тему и содержимое письма, которое нужно отправить на список получателей из параметра contacts. Если объект customMessage отсутствует - будет отправлено "дефолтное" письмо, выбранное для транзакционной рассылки на главном окне AMS.

 

subject - тема письма. Должно передаваться в виде base64 строки, содержащей тему письма в кодировке UTF-8

 

htmlPart - html часть письма. Должна передаваться в виде base64 строки, содержащей html код письма в кодировке UTF-8

 

textPart - текстовая часть письма. Должна передваться в виде base64 строки, содержащей текстовую часть письма в кодировке UTF-8.

 

messageType - тип письма. Возможны два варианта: Html или Text. Если messageType=Html - параметр htmlPart не должен быть пустым. Если messageType=Text - параметр textPart не должен быть пустым. Данный параметр имеет ту же логику, что и эта настройка в редакторе писем:

apimsgtype

 

textPartMode - режим использования текстовой части Html писем. Возможные значения: ExtractFromHtml (извлечь текстовую часть из html части), CustomTextPart (задать свою текстовую часть), NoTextPart (отключить текстовую часть). Данный параметр имеет ту же логику, что и эта настройка в редакторе писем:

apitextpartmode

 

attachments - массив с вложениями, которые нужно приложить к письму. Содержит список объектов, каждый из которых хранит имя файла вложения и его содержимое в виде base64 строки.

 

htmlAttachments - массив с картинками, которые нужно встроить и передать вместе с письмом. Содержит список объектов, каждый из которых хранит имя файла картинки и ее содержимое в виде base64 строки.
 
Например, если html код вашего письма содержит <img src="image1.jpg"> и при этом массив htmlAttachments содержит файл image1.jpg - то при сборке письма IMG тэг поменяется на <img src="cid:b3f106b5009ed27a741cb6030@domain.com"> и картинка будет встроено в письмо как вложение.

 

customHeaderLines - опциональный массив строк, который необходимо добавить в конец стандартного заголовка письма. Строки добавляются в загловок "как есть", без какого либо кодирования. Если параметр отсутствует - письмо отправляется со стандартным заголовком. Данный параметр является аналогом этой настройки Редактора писем:

apicustomheaders

curl -X POST -H 'Content-Type: application/json' -i 'http://127.0.0.1/api/v1' --data '{

 "jsonrpc":"2.0",

 "method":"postSendingJob",

 "params":{

   "apiKey":"5EB20EC3-F672-4A26-8F65-9FC162ED4EAB",

   "jobID":"MyJobType_ID_43455353",

   "mailingID":78,

   "contacts":[

     {

       "ID":"1",

       "Email":"billgates@microsoft.com",

       "FullName":"Bill Gates",

       "mCity":"Redmont"

     },

     {

       "ID":"2",

       "Email":"jeffbezos@amazon.com",

       "FullName":"Jeff Bezos",

       "mCity":"New York"

     },

     {

       "ID":"3",

       "Email":"support@bspdev.com",

       "FullName":"BSPDEV - Support",

       "mCity":"Saint-Petersburg"

     }

   ],

   "customMessage":{

     "subject":"VGhpcyBpcyBhIHRlc3Qgc3ViamVjdA==",

     "htmlPart":"PGh0bWw+PGhlYWQ+DQo8bWV0YSBjb250ZW50PSJ0ZXh0L2h0bWw7IGNoYXJzZXQ9dXRmLTgiIGh0dHAtZXF1aXY9Q29udGVudC1UeXBlPg0KPC9oZWFkPg0KPGJvZHkgYmdDb2xvcj0iI2ZmZmZmZiI+DQo8ZGl2IGFsaWduPWxlZnQ+dGhpcyBpcyBhIGN1c3RvbSBtZXNzYWdlIGJvZHk8L2Rpdj48L2JvZHk+PC9odG1sPg==",

     "textPart":"",

     "messageType":"Html",

     "textPartMode":"ExtractFromHtml",

     "attachments":[

       {

         "fileName":"file.doc",

         "fileContent":"UEsDBBQACAAIAEAv5F.....=="

       }

     ],

     "htmlAttachments":[

       {

         "fileName":"image1.jpg",

         "fileContent":"h0L2h0bWw7IGNsd32d.....=="

       },

       {

         "fileName":"image2.jpg",

         "fileContent":"vbSBtZXNzYWdlIGJv2d.....=="

       }

     ]

   },

   "customHeaderLines":[

     "Precedence: bulk",

     "X-Mailer: [%%ORandText,XMailers%%]"

   ]

 },

 "id":"1"

}'

Описание параметров, примечания

 

Пример ответа

В случае успеха строка "ОК" или ошибка.

{

 "jsonrpc":"2.0",

 "result":"OK",

 "id":1

}