Управление рассылками через API |
|
|
|
Управление рассылками через API |
|
|
Управление рассылками через API |
|
|
|
Управление рассылками через API |
|
|
Перед использованием API необходимо зайти в окно Настройки->Настройки API, задать параметры и включить 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 сервера при использовании HTTPS протокола в несколько раз ниже чем с обычным HTTP. Это может быть проблемой если вы планируете делать частые вызовы команд API.
При первом запуске программы генерируется новый уникальный Ключ API, которые необходимо использовать при вызове команд API. При желании вы можете Создать новый ключ с помощью соответствующей кнопки.
После того, как все настройки были заданы нажмите кнопку Включить API сервер.
Так же, в некоторых случаях, вам может потребоваться добавить AMS в исключения файрвола и, возможно, изменить настройки вашего роутера если вы хотите что API сервер AMS был доступен из вне (из интернета).
Для отправки команд API используйте URL http://127.0.0.1/api/v1 или https://127.0.0.1/api/v1 где 127.0.0.1 это IP адрес компьютера (сервера) где установлен AMS. Используются HTTP POST запросы, 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.
Запрос в общепринятом виде для команды curl, красным цветом показаны параметры команды curl, синим цветом выделен непосредственно сам JSON запроса, зеленым цветом - имя вызываемой команды 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":"38091FE7-5516-4F5B-9455-4A340BFEC875"
},
"id":"1"
}'
method - имя вызываемой команды
params - параметры вызываемой команды.
поля отмеченные синим - jsonrpc и id относятся к спецификации JSON-RPC 2.0 и, обычно, никогда не меняются.
Ответ:
{
"jsonrpc":"2.0",
"result":[
{
"id":73,
"name":"Example Mailing",
"type":"mailing",
"state":"idle",
"createDate":"2003-11-13",
"lastStartDate":"2023-10-18T08:13:15.568",
"approxSpeed":"0\/min",
"lastStopByPostmaster":false,
"enableCustomExcludeList":false,
"customExcludeListID":-1,
"enableExcludeListFile":false,
"excludeListFileName":"",
"excludeListFileType":"emails",
"progressInfo":{
"percentDone":0,
"total":1,
"sent":0,
"notSent":0,
"bad":0,
"refused":0,
"excluded":0,
"opened":0,
"clicks":0
}
}
],
"id":1
}
Результат выполнения команды содержится в поле result, которое может быть числом, строкой, объектом или массивом в зависимости от того какая какая команда исполняется. Поля отмеченные синим jsonrpc и id относятся к спецификации JSON-RPC 2.0 и, обычно, никогда не меняются.
В случае если были переданы не верные параметры команды или при ее выполнении возникла ошибка - ответ с ошибкой будет выглядеть таким образом:
{
"jsonrpc":"2.0",
"error":{
"code":-32603,
"message":"Mailing with id=716 not exists"
},
"id":1
}
Зеленым выделена информация об ошибке - сode - ее код и message - текст ошибки. Поля отмеченные синим jsonrpc и id относятся к спецификации JSON-RPC 2.0 и, обычно, никогда не меняются.
•Команды API всегда выполняются последовательно, одна за одной, в главном потоке AMS. Даже если вы отправите команды параллельно в несколько потоков - они встанут в очередь и будут выполнены последовательно.
•Поскольку команды выполняются в главном потоке приложения - слишком частая отправка команд может привести к снижению отзывчивости интерфейса AMS.
•Некоторые команды API не могут быть выполнены из-за текущих действий пользователя, работающего в интерфейсе AMS. Например, нельзя удалить список рассылки если в этот момент его просматривает или редактирует пользователь. В таких случаях вы получите ошибку, что данный ресурс сейчас занят и предложение повторить команду позднее.
•Некоторые команды, например создающие/редактирующие Рассылки, Письма, Профили отправки, работают с относительно сложными объектами, чье JSON представление может быть довольно объемным. Чтобы было проще разобраться с тем, какие данные нужно отправлять - вы можете создать Рассылку, Письмо, Профиль отправки и т.д. с нужными настройками вручную в интерфейсе AMS, после чего получить JSON представление созданного объекта через команду getНужныйВамОбъект. Таким образом, вы получите JSON объекта с нужными вам настройками, чтобы в дальнейшем использовать его в качестве образца.
Команда API |
Описание |
Управление рассылками |
|
Создать новую рассылку |
|
Изменить настройки рассылки |
|
Удалить рассылку |
|
Получить список имеющихся рассылок всех типов |
|
Получить список только транзакционных рассылок |
|
Получить детальную информацию о рассылке |
|
Запустить рассылку |
|
Остановить рассылку |
|
Управление учетными записями отправителя |
|
Добавить учетную запись отправителя |
|
Редактировать настройки учетной записи |
|
Удалить учетную запись |
|
Получить список имеющихся учетных записей |
|
Получить детальную информацию об учетной записи |
|
Управление списками рассылки |
|
Создать список рассылки |
|
Изменить настройки списка рассылки |
|
Удалить список рассылки (на данный момент команда не реализована) |
|
Получить список имеющихся списков рассылки |
|
Получить размер списка рассылки |
|
Получить содержимое списка рассылки |
|
Удалить все записи из списка рассылки |
|
Управление контактами (получателями) |
|
Добавить получателей в список рассылки |
|
Редактировать получателя в списке рассылки |
|
Удалить получателей из списка рассылки |
|
Управление письмами |
|
Создать письмо |
|
Изменить письмо |
|
Удалить письмо |
|
Получить список имеющихся писем |
|
Получить детальную информацию о письме |
|
Управление профилями отправки |
|
Создать профиль отправки |
|
Изменить настройки профиля отправки |
|
Удалить профиль отправки |
|
Получить список имеющихся профилей отправки |
|
Получить детальную информацию о профиле отправки |
|
Управление ссылками для сбора статистики по кликам и открытым письмам (ссылками на скрипт amsweb.php) |
|
Добавить ссылку на amsweb.php |
|
Изменить настройки ссылки |
|
Удалить ссылку |
|
Получить список имеющихся ссылок на amsweb.php |
|
Управление DKIM подписями |
|
Добавить DKIM подпись |
|
Изменить DKIM подпись |
|
Удалить DKIM подпись |
|
Получить список имеющихся DKIM подписей |
|
Получить детальную информацию о DKIM подписи |
|
Управления аккаунтами для получения статистики от postmaster.mail.ru |
|
Добавить аккаунт для получения статистики с postmaster.mail.ru |
|
Изменить настройки аккаунта |
|
Удалить аккаунт |
|
Получить список имеющихся аккаунтов postmaster.mail.ru |
|
Управление списками прокси |
|
Создать список прокси |
|
Изменить настройки списка прокси |
|
Удалить список прокси |
|
Задать содержимое прокси листа (добавить прокси в список) |
|
Получить список имеющихся списков прокси |
|
Получить информацию о прокси листе |
|
Получение статистики и изменение настроек smtp релеев, используемых в активных рассылках |
|
Получить состояния релеев у активной рассылки (число отправленных писем, ошибки) |
|
Изменить параметры заданного релея у активной рассылки |
|
Получение статистики и изменение настроек прокси, используемых в активных рассылках |
|
Получить состояния прокси у активной рассылки (число отправленных писем, ошибки) |
|
Изменить параметры заданного прокси у активной рассылки |
|
Управление транзакционными рассылками |
|
Отправить задание на отправку в очередь транзакционной рассылки |
|
Получить результат отправки задания |
|
Управление расписанием запуска рассылок |
|
Проверить запущен ли планировщик рассылок AMS |
|
Запустить планировщик рассылок AMS |
|
addMailing |
||
|
||
Пример вызова: { "jsonrpc":"2.0", "method":"addMailing", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "name":"New Mailing from API", "type":"mailing", "settings":{ "senderAccount":{ "id":22 }, "mailList":{ "id":263 }, "message":{ "id":189 }, "deliveryPreset":{ "id":1026 }, "controlEmailsSending":{ "enabled":true, "controlEmails":[ "seed1@email.com" ], "sendingIntervalMode":"byMessagesNumber", "sendingIntervalValue":1000 }, "postmasterIntegration":{ "enabled":true, "postmasterAccountID":4, "postmasterDomains":[ "mydomain.com" ], "enableMailingAutoStop":true, "autoStopPostmasterData":"spam", "autoStopValueType":"spamPercent", "autoStopValue":1.5, "autoStopMode":"suspend", "autoSuspendMinutes":122 }, "disableSendingLog":false, "enableCustomExcludeList":false, "customExcludeListID":-1, "enableExcludeListFile":false, "excludeListFileName":"", "excludeListFileType":"emails", "customFields":[ "", "", "", "", "", "", "", "", "", "" ] } }, "id":"1" } |
||
Результат вызова содержит ID созданной рассылки или ошибку: |
||
{ "jsonrpc":"2.0", "result":{ "newResourceID":243 }, "id":1 } |
getTransactionalMailings |
Команда выдает список имеющихся транзакционных рассылок.
Фактически, это почти то же самое, что команда getMailings, но выдает только те рассылки, у которых поле type содержит "transactional"
Описание параметров:
apiKey - ключ доступа к API |
Пример вызова:
{ "jsonrpc":"2.0", "method":"getTransactionalMailings", "params": {"apiKey": "38091FE7-5516-4F5B-9455-4A340BFEC875"}, "id":"1" } |
Результат вызова содержит массив с имеющимися транзакционными рассылками и их состояниями. Описание возвращаемых полей дано у команды getMailings выше. |
{ "jsonrpc":"2.0", "result":[ { "id":76, "name":"Another mailing", "type":"transactional", "state":"idle", "createDate":"2024-03-02", "lastStartDate":"", "progressInfo":{ "jobsQueued":0, "contactsQueued":0, "total":0, "sent":0, "notSent":0, "bad":0, "refused":0, "excluded":0, "opened":0, "clicks":0 } } ], "id":1 } |
getMailing |
Команда выдает подробную информацию о рассылке: ее состояние и настройки.
Описание параметров:
apiKey - ключ доступа к API id - id рассылки, данные о которой нужно получить. Список имеющихся рассылок можно получить с помощью команды getMailings. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"getMailing", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":73 }, "id":"1" } |
Результат вызова содержит объект с информацией о рассылке. Вы можете использовать полученный объект как образец для создания или редактирования рассылок (см. команды addMailing и editMailing).
apiKey - ключ доступа к API
id - id рассылки, обязательный параметр
name - имя рассылки.
type - тип рассылки. Возможные значения:
mailing - обычная рассылка validation - рассылка для валидации базы transactional - транзакционная рассылка..
state - состояние рассылки. Возможные значения:
idle - рассылка остановлена working - рассылка работает stopping - рассылка в процессе остановки. Поскольку остановка рассылки может занимать некоторое время - для него выделен отдельный статус. Пока рассылка останавливается ее нельзя удалить или запустить, эти операции возможны только если состояние рассылки "idle".
createDate - дата создания рассылки
lastStartDate - дата и время последнего запуска рассылки.
approxSpeed - средняя скорость рассылки (доступна для работающих рассылок).
lastStopByPostmaster - последняя остановка рассылки была вызвана функцией интеграции с postmaster.mail.ru т.е. письма стали попадать в "спам" или в "возможно спам" на mail.ru
progressInfo - объект с прогрессом рассылки.
percentDone - % прогресса выполнения рассылки (всегда 0 если type = transactional)
total - общее число адресов в списке контактов, по которому идет рассылка.
sent - число отправленных писем
notSent - число не отправленных писем
bad - число адресов получателей, которые определились как не существующие/плохие (см. окно Настройки->Smtp правила).
refused - число адресов получателей, на которые не удалось доставить почту в режиме встроенного смтп сервера по причине ошибок, связанных с блокировкой IP, домена или содержимого письма (см. окно Настройки->Smtp правила).
exсluded - число адресов получателей, на которые не были отправлены письма т.к. эти адреса находились в списках исключений или попадали под правила исключений.
opened - число писем, открытых получателями.
clicks - число кликов по ссылкам внутри писем.
jobsQueued - число заданий в очереди транзакционной рассылки (доступно только если type = transactional).
contactsQueued - число адресов в очереди транзакционной рассылки (доступно только если type = transactional).
good - число адресов, определившиеся как "хорошие" в процессе валидации базы (доступно только если type = validation).
undetermined - число адресов, чей результат валидации не удалось определить из-за каких-либо ошибок (доступно только если type = validation).
settings - объект, в котором передаются настройки рассылки:
senderAccount.id - id Учетной записи отправителя, выбранной для рассылки.
mailList.id - id Списка рассылки, выбранного для рассылки.
message.id - id письма, выбранного для рассылки.
deliveryPreset.id - id профиля отправки, выбранного для рассылки.
controlEmailSettings - объект, в котором задаются настройки отправки писем на контрольные адреса в процессе рассылки.
enabled - разрешает отправку контрольных писем.
controlEmails - массив с email адресами, на которые будут уходить контрольные письма во время рассылки.
sendingIntervalMode - режим отправки контрольных писем. Возможные значения:
byMessagesNumber - отправлять контрольные письма на заданные адреса после отправки числа обычных писем byMailingProgress - отправлять контрольные письма на заданные адреса через заданный % прогресса рассылки.
sendingIntervalValue - в зависимости от значения параметра sendingIntervalMode - число писем или % прогресса, после которого должна выполняться отправка контрольных писем на адреса, заданные в массиве controlEmails.
postmasterIntegration - объект, в котором задаются настройки интеграции с postmaster.mail.ru
enabled - разрешает интеграцию с postmaster.mail.ru
postmasterAccountID - id аккаунта postmaster.mail.ru который содержит информацию по доменам, которые нужно отслеживать. Для получения списка доступных аккаунтов используйте команду getPostmasterAccounts.
postmasterDomains - массив с доменами, статистику по которым нужно отслеживать. Эти домены должны быть подключены к выбранному аккаунту постмастера на https://postmaster.mail.ru
enableMailingAutoStop - разрешить автоматическую остановку рассылки если статистика постмастера показывает, что письма стали уходить в "спам" или "возможно спам"
autoStopPostmasterData - какие данные postmaster.mail.ru будут анализироваться для остановки рассылки. Возможные значения:
spam - число или процент писем, попавших в Спам probablySpam - число или процент писем, попавших в Возможно спам spamOrProbablySpam - число или процент писем, попавших в Спам ИЛИ в Возможно спам.
autoStopValueType - определяет тип информации о письмах, поправших в спам или возможно спам, которые будут анализироваться для остановки рассылки. Возможные значения:
spamMsgNumber - анализируется число писем, попавших в спам или возможно спам spamPercent - анализируется процент писем, попавших в спам или возможно спам.
autoStopValue - в зависимости от содержимого параметра autoStopValueType - число или процент писем, попавших в спам или возможно спам, при достижении которого рассылка будет автоматически остановлена.
autoStopMode - режим остановки рассылки, возможные значения:
fullStop - полная остановка рассылки suspend - приостановить рассылку на заданное время.
autoSuspendMinutes - число минут, на которые нужно приостановить рассылку если параметр autoStopMode содержит значение "suspend".
disableSendingLog - отключить запись логов рассылки для экономии места на диске.
enableCustomExcludeList - включить персональный список исключений для этой рассылки. В качестве персонального списка можно выбрать любой список рассылки На адреса, которые есть в этом списке почта отправляться не будет. Персональный список исключений работает совместно с "глобальным" списком исключений, который задается в окне управления списками рассылки.
customExcludeListID - id списка рассылки, который будет использоваться как персональный список исключений. Получить список доступных списков рассылки можно командой getMailingLists
enableExcludeLisfFile - включить дололнительный список исключений в виде текстового файла файла на диске. Этот дополнительный список исключений работает совместно с персональным списком исключений, заданным в параметре customExcludeListID и глобальным списком исключений, заданным в окне управления списками рассылки. Таким образом, у рассылки может быть 3 разных списка исключений - глобальный и два персональных дополнительных.
excludeListFileName - путь к файлу на диске с дополнительным списком исключений.
excludeListFileType - содержимое файла со списком исключений, возможные значения:
emails - файл содержит email адреса md5Hashes - файл содержит MD5 хэши email адресов sha1Hashes - файл содержит sha1 хэши email адресов sha256Hashes - файл содержит sha256 хэши email адресов.
CustomFields - массив строк (до 10 строк) в которых можно задать любые пользовательские данные, привязанные к этой рассылке. В последствии, эти данные могут быть подставлены в любое место письма или его заголовка с помощью макросов [%%MailingCustomField1%%] ... [%%MailingCustomField10%%] |
{ "jsonrpc":"2.0", "result":{ "id":73, "name":"Example Mailing", "type":"mailing", "state":"idle", "createDate":"2003-11-13", "lastStartDate":"2023-10-18T08:13:15.568", "approxSpeed":"0\/min", "lastStopByPostmaster":false, "progressInfo":{ "percentDone":0, "total":1, "sent":0, "notSent":0, "bad":0, "refused":0, "excluded":0, "opened":0, "clicks":0 }, "settings":{ "senderAccount":{ "id":17, "name":"Example sender account" }, "mailList":{ "id":270, "name":"Example list" }, "message":{ "id":1, "subject":"Example message", "name":"my test message" }, "deliveryPreset":{ "id":18, "name":"Example preset" }, "controlEmailsSending":{ "enabled":false, "controlEmails":[
], "sendingIntervalMode":"byMessagesNumber", "sendingIntervalValue":1000 }, "postmasterIntegration":{ "enabled":false, "postmasterAccountID":0, "postmasterDomains":[
], "enableMailingAutoStop":false, "autoStopPostmasterData":"spam", "autoStopValueType":"spamMsgNumber", "autoStopValue":0, "autoStopMode":"fullStop", "autoSuspendMinutes":120 }, "disableSendingLog":false, "enableCustomExcludeList":false, "customExcludeListID":-1, "enableExcludeListFile":false, "excludeListFileName":"", "excludeListFileType":"emails", "customFields":[ "", "", "", "", "", "", "", "", "", "" ] } }, "id":1 } |
startMailing |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"startMailing", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":164, "startMode":"continue", "stopMode":"LimitProcessedMessages", "stopValue":10000 }, "id":"1" } |
||
Результат вызова содержит строку "ОК" или ошибку запуска. |
||
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
stopMailing |
Команда останавливает рассылку.
Описание параметров:
apiKey - ключ доступа к API.
id - id рассылки, которую нужно остановить, обязательный параметр. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"stopMailing", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":164 }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
addSenderAccount |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"addSenderAccount", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "accountName":"Example account", "senderName":"John Smith", "senderEmail":"maillist@mailserver.com", "replyToEmail":"sales@mailserver.com", "organization":"My Company", "espDomain":"espdomain.com" }, "id":"1" } |
||
Результат вызова содержит ID созданной учетной записи или ошибку: |
||
{ "jsonrpc":"2.0", "result":{ "newResourceID":18 }, "id":1 } |
editSenderAccount |
Команда редактирует учетную запись отправителя.
Описание параметров:
apiKey - ключ доступа к API.
id - id учетной записи, которую нужно изменить, обязательный параметр.
accountName - имя учетной записи.
senderName - имя отправителя.
senderEmail - email отправителя, обязательный параметр.
replyToEmail - reply-to email
organization - значение поля Организация
espDomain - значение поля ESP домен (для этого домена может быть добавлена вторая DKIM подпись в заголовок письма).
Вы можете передать только те поля, которые желаете изменить. Если какой-то параметр отсутствует - его значение останется без изменений. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"editSenderAccount", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":18, "accountName":"New account name", "senderName":"Bill Gates", "senderEmail":"bill@mailserver.com", "replyToEmail":"sales@microsoft.com", "organization":"Microsoft", "espDomain":"" }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
deleteSenderAccount |
Команда удаляет учетную запись отправителя
Описание параметров:
apiKey - ключ доступа к API.
id - id учетной записи, которую нужно удалить, обязательный параметр. Получить список имеющихся учетных записей можно с помощью команды getSenderAccounts. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"deleteSenderAccount", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":18 }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
getSenderAccounts |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"getSenderAccounts", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875" }, "id":"1" } |
||
Результат вызова содержит массив с имеющимися Учетными записями отправителя:
id - id учетной записи, которую нужно изменить, обязательный параметр.
accountName - имя учетной записи.
senderName - имя отправителя.
senderEmail - email отправителя, обязательный параметр.
replyToEmail - reply-to email
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 } |
getSenderAccount |
Команда возвращает Учетную запись отправителя.
Описание параметров:
apiKey - ключ доступа к API.
id - id учетной записи, которую нужно получить. Список всех имеющихся учетных записей можно получить с помощью команды getSenderAccounts |
Пример вызова:
{ "jsonrpc":"2.0", "method":"getSenderAccount", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":17 }, "id":"1" } |
Результат вызова содержит объект Учетной записи отправителя или ошибку:
id - id учетной записи, которую нужно изменить, обязательный параметр.
accountName - имя учетной записи.
senderName - имя отправителя.
senderEmail - email отправителя, обязательный параметр.
replyToEmail - reply-to email
organization - значение поля Организация
espDomain - значение поля ESP домен (для этого домена может быть добавлена вторая DKIM подпись в заголовок письма). |
{ "jsonrpc":"2.0", "result":{ "id":17, "accountName":"Example sender account", "senderName":"Jhon Smith", "senderEmail":"maillist@mailserver.com", "replyToEmail":"sales@mailserver.com", "organization":"", "espDomain":"" }, "id":1 } |
addMailingList |
||
|
||
Пример создания локального списка рассылки:
{ "jsonrpc":"2.0", "method":"addMailingList", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "listName":"New MailList from API", "parentID":468, "listType":"local" }, "id":"1" }
Пример создания подключения к внешней базе данных через ADO/ODBC:
{ "jsonrpc":"2.0", "method":"addMailingList", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "listName":"New DB Connection from API", "parentID":468, "listType":"Remote", "remoteDBOptions":{ "adoConnectionString":"Provider=MSDASQL.1;Persist Security Info=False;Data Source=SqliteTest", "remoteAccessMode":"DirectConnection", "remoteTableName":"List90", "remoteEmailMapping":"Email", "remoteFullNameMapping":"FullName", "remoteIDMapping":"ID" } }, "id":"1" } |
||
Результат вызова содержит ID созданного списка рассылки или ошибку: |
||
{ "jsonrpc":"2.0", "result":{ "newResourceID":21 }, "id":1 } |
editMailingList |
Команда редактирует настройки списка рассылки или подключения к внешней базе данных.
Описание параметров: команда может принимать все те же параметры, что и команда addMailingList, но так же требует обязательный параметр c ID редактируемого списка.
apiKey - ключ доступа к API.
id - id списка рассылки, который требуется отредактировать, обязательный параметр. Получить список списков рассылки и их ID можно с помощью команды getMailingLists.
parentID - id списка-родителя в дереве списков рассылки. Может использоваться чтобы изменить список-родитель для данного списка. Получить список списков рассылки и их ID можно с помощью команды getMailingLists.
listType - тип списка рассылки. Возможные значения:
Local - будет создан обычный локальный список рассылки. Remote - будет создано подключение к внешней базе данных через ADO/ODBC. если параметр не задан - значение по умолчанию - local.
remoteDBOptions - если listType=Remote, то в этом объекте передаются настройки подключения к внешней базе данных:
adoConnectionString - строка подключения к базе данных. Чтобы получить строку подключения - вы можете вначале создать подключение вручную в интерфейсе AMS, после чего использовать полученную строку подключения для создания новых подключений через API.
remoteAccessMode - режим подключения к внешней базе данных. Возможные значения:
DirectConnection - прямое подключение к базе данных. Сервер базы данных должен быть доступен, в противном случае получить данные будет не возможно. Так же таблица во внешней БД должна обязательно содержать поле ID с уникальным идентификатором записи. Лучше всего подойдет автоинкрементное поле типа Integer. Если поля ID в таблице нет - используйте режим LocalCopy ! LocalCopy - создание копии данных из вашей БД в локальной таблице AMS. Копия данных создается при каждом перезапуске рассылки с начала, далее используется локальная копия данных без обращение к вашему серверу БД.
remoteTableName - имя таблицы во внешней базе данных к которой выполняется подключение. Равносильно SQL запросу SELECT * FROM remoteTableName
remoteSqlQuery - SQL запрос, который возвратит из внешней базы данных нужные вам данные.
remoteEmailMapping - имя поля в таблице внешней БД, содержащее email адреса получателей. Обязательно должно быть задано.
remoteFullNameMapping - имя поля в таблице внешней БД, содержащее имена получателей (которые будут использованы воле Кому: (To:) отправляемых писем).
remoteIDMapping - имя поля в таблице внешней БД, содержащее уникальные идентификаторы записей. Лучше всего - автоинкрементное поле типа Integer. Значение обязательно должно быть задано если remoteAccessMode=DirectConnection ! |
Пример вызова для изменения имени списка рассылки:
{ "jsonrpc":"2.0", "method":"editMailingList", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":261, "listName":"New List Name" } }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
getMailingLists |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"getMailingLists", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875" }, "id":"1" } |
||
Результат вызова содержит массив с имеющимися списками рассылки:
id - id списка рассылки.
parentID - id списка-родителя в дереве списков рассылки. Корневой список "Все списки" (в английской версии - Mailing Lists) имеет parentID=-1, у всех остальных списков он больше 0.
listName - имя списка рассылки.
size - размер списка рассылки (число адресов получателей).
lastMailing - дата последнего запуска рассылки по этому списку. |
||
{ "jsonrpc":"2.0", "result":[ { "id":102, "parentID":-1, "listName":"Mailing Lists", "listType":"Local", "size":0, "lastMailing":"" }, { "id":270, "parentID":102, "listName":"Example list", "listType":"Local", "size":2, "lastMailing":"" }, { "id":271, "parentID":270, "listName":"Sub list", "listType":"Local", "size":6900, "lastMailing":"" } ], "id":1 } |
getMailingListSize |
Команда число записей в списке рассылки.
Описание параметров:
apiKey - ключ доступа к API.
id - id списка рассылки, размер которого нужно получить. Получить список списков рассылки и их ID можно с помощью команды getMailingLists. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"getMailingListSize", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":270 }, "id":"1" } |
Результат вызова содержит число записей в списке рассылки или ошибку. |
{ "jsonrpc":"2.0", "result":4800, "id":1 } |
getMailingListDataSet |
Команда возвращает содержимое списка рассылки.
Поскольку список рассылки может содержать миллионы адресов - команда отдает данные постранично.
Описание параметров:
apiKey - ключ доступа к API.
id - id списка рассылки, содержимое которого нужно получить, обязательный параметр.
getPageNo - номер страницы, которую вы хотите получить, обязательный параметр.
recordsPerPage - число записей на странице, обязательный параметр. Максимальное число записей на странице - 65535.
sortByField - опциональный параметр с именем поля списка рассылки, по которому нужно сделать сортировку.
sortDescending - если true - сортировка по полю sortByField будет выполнена в обратном порядке.
Число страниц с записями можно посчитать разделив общее число записей в списке рассылки на желаемый размер записей на странице, передаваемый в параметре recordsPerPage. Общее число записей можно получить с помощью команды getMailingListSize, а так же вызвав команду getMailingListDataSet - ее результат так же содержит текущий размер списка рассылки.
Обратите внимание, что размер списка рассылка может измениться в любой момент если пользователь добавил или удалил записи в интерфейсе AMS или если сработали какие-либо правила, модифицирующие списки рассылки (клик на ссылку для отписки, правила обработки почты в Процессоре входящей почты и т.д.). Поэтому вам нужно пересчитывать размер доступных страниц после каждого вызова getMailingListDataSet (или командой getMailingListSize перед каждым вызовом). |
Пример вызова:
{ "jsonrpc":"2.0", "method":"getMailingListDataSet", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":270, "getPageNo":1, "recordsPerPage":100, "sortByField":"FullName", "sortDescending":false }, "id":"1" } |
Результат вызова содержит информацию о полях списка рассылки и содержимое запрошенных записей или ошибку:
totalRowsCount - текущий размер списка рассылки на момент выполнения команды. Используйте это число для подсчета числа страниц с данными (totalRowsCount / recordsPerPage). Обратите внимание, что размер списка рассылка может измениться в любой момент ! Поэтому, если вы отображаете число доступных страниц в каком-то своем интерфейсе, вам нужно пересчитывать число страниц после каждого вызова команды.
dataSetFields - массив с информацией о полях списка рассылки:
name - имя поля списка рассылки.
type - тип поля в базе данных: autoinc, string, integer, float, memo, blob и т.д.
Обратите внимание, что набор и тип полей может измениться в любой момент если пользователь изменил структуру списка рассылки в интерфейсе AMS или изменил SQL запрос для подключения к внешней базе данных ! Если вы хотите отображать данные в каком-то своем интерфейсе - вам нужно быть готовым изменить набор полей таблицы в вашем интерфейсе после каждого вызова команды getMailingListDataSet
dataSetRows - массив с содержимым записей списка рассылки. Данные идут в том же порядке, что и перечень полей в массиве dataSetFields. Тип данных может быть различным в зависимости от типа поля - строка, число и т.д. Если возвращаются данные blob поля - они будут закодированы в base64. |
{ "jsonrpc":"2.0", "result":{ "totalRowsCount":2, "dataSet":{ "dataSetFields":[ { "name":"ID", "type":"ft_AutoInc" }, { "name":"Email", "type":"ft_String" }, { "name":"FullName", "type":"ft_String" }, { "name":"City", "type":"ft_String" } ], "dataSetRows":[ [ 2, "billgates@microsoft.com", "Bill Gates", "Redmont" ], [ 1, "user@mailserver.com", "Jhon Smith", "New York" ] ] } }, "id":1 } |
clearMailingList |
Команда удаляет все записи из списка рассылки.
Описание параметров:
apiKey - ключ доступа к API.
id - id списка рассылки, который нужно очистить, обязательный параметр. Получить список списков рассылки и их ID можно с помощью команды getMailingLists.
Очистить можно только локальный список рассылки. Подключения к внешним базам данных всегда открываются в режиме только для чтения. Нельзя удалить список, если он используется в запущенных рассылках или если с ним работает пользователь в интерфейсе AMS (загружает или просматривает записи и т.д.). |
Пример вызова:
{ "jsonrpc":"2.0", "method":"clearMailingList", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":270 }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
addContacts |
Команда добавляет получателей в список рассылки
Описание параметров:
apiKey - ключ доступа к API.
listID - id списка рассылки, в который нужно добавить записи, обязательный параметр. Список доступных списков рассылки можно получить с помощью команды getMailingLists. Можно добавлять записи только в локальные списки рассылки, подключения к внешним базам данных всегда открываются в режиме Только для чтения. Нельзя изменять (добавлять, изменять, удалять) записи в списках рассылки, которые в данный момент используются в запущенных рассылках.
allowDuplicates - если true то разрешает добавление дубликатов (email) в список рассылки. По умолчанию false.
contacts - массив с получателями, которых нужно добавить в список рассылки. При формировании массива Contacts придерживайтесь следующих правил:
•Массив должен содержать минимум 1 и максимум 10000 получателей. •Все элементы массива contacts должны содержать одинаковый набор полей в одинаковой последовательности ! Т.е. не может быть, что у одного контакта есть поле City, а у другого нет (может быть пустое значение поля, но само поле должно быть). •Массив должен содержать как минимум одно поле Email. •Если массив содержит поле ID - его значение игнорируется т.к. ID контакта генерируется автоматически в автоинкрементном поле базы данных, вы не можете задавать или изменять его значение. •Набор полей, который имеется в целевом списке рассылки можно получить с помощью команды getMailingListDataSet. •У разных списков рассылки может быть разный набор полей. И он может быть изменен пользователем в интерфейсе AMS. •Значения всех полей контакта должны передаваться в виде строк (например, передавать не число 10, а строку “10”), при добавлении записи в базу данных значение будет автоматически приведено к типу, который ожидает целевое поле списка рассылки (например строка "10" автоматически преобразуется в число если целевое поле типа Integer). В случае не удачной конверсии полю будет присвоено пустое значение. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"addContacts", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "listID":270, "allowDuplicates":false, "contacts":[ { "Email":"test@mail.com", "FullName":"User 1", "City":"Moscow" }, { "Email":"test2@mail.com", "FullName":"User 2", "City":"" } ] }, "id":"1" } |
Результат вызова команды содержит следующие данные:
recordsAdded - число успешно добавленных записей.
badEmailSyntax - число записей, которые не были добавлены из-за не верного синтаксиса email адреса (отсутствие @, не допустимые символы и т.д.).
badSyntax - если badEmailSyntax > 0 - ответ содержит массив badSyntax с копией записей из входного массива contacts, которые не прошли контроль синтаксиса email.
excluded - число записей, которые не были добавлены из-за того, что попали под "Правила Исключений", запрещающие загрузку таких записей. Сам список Правил исключений задается в окне управления списками рассылки в интерфейсе AMS.
excludedByRules - если excluded > 0 - ответ содержит массив excludedByRules с копией записей из входного массива contacts, которые попали под Правила исключений.
duplicatesFound - число записей, которые не были добавлены из-за того, что такой email уже есть в целевом списке рассылки (контроль дубликатов выполняется если allowDuplicates=false).
duplicates - если duplicatesFound > 0 - ответ содержит массив duplicates с копией записей из входного массива contacts, которые не прошли контроль дубликатов. |
{ "jsonrpc":"2.0", "result":{ "duplicates":[ { "Email":"test@mail.com", "FullName":"User 1", "City":"Spb" } ], "recordsAdded":1, "badEmailSyntax":0, "excluded":0, "duplicatesFound":1 }, "id":1 } |
editContact |
Команда редактирует контакт в списке рассылки.
Описание параметров:
apiKey - ключ доступа к API.
listID - id списка рассылки, в котором нужно отредактировать запись, обязательный параметр. Список доступных списков рассылки можно получить с помощью команды getMailingLists. Можно изменять записи только в локальных списках рассылки, подключения к внешним базам данных всегда открываются в режиме Только для чтения. Нельзя изменять (добавлять, изменять, удалять) записи в списках рассылки, которые в данный момент используются в запущенных рассылках.
contactID - id контакта, который нужно отредактировать. Список контактов можно получить с помощью команды getMailingListDataSet.
allowDuplicates - если true то разрешает изменение контакта если новое значение поля Email уже есть в целевом списке рассылки. По умолчанию значение false и при нахождении дубликата будет ошибка.
contactData - объект с данными контакта для редактирования. Вы можете передать только те поля, значения которых хотите отредактировать. У остальных полей значение не изменится. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"editContact", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "listID":270, "contactID":1, "allowDuplicates":false, "contactData":{ "Email":"new-email@mail.com", "FullName":"New name" } }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
deleteContacts |
Команда удаляет контакты из списка рассылки.
Описание параметров:
apiKey - ключ доступа к API.
listID - id списка рассылки, из которого нужно удалить записи, обязательный параметр. Список доступных списков рассылки можно получить с помощью команды getMailingLists. Можно удалять записи только в локальных списках рассылки, подключения к внешним базам данных всегда открываются в режиме Только для чтения. Нельзя изменять (добавлять, изменять, удалять) записи в списках рассылки, которые в данный момент используются в запущенных рассылках.
deleteID - массив с id контактов, которые нужно удалить. Должен содержать не менее 1 и не более 5000 id. Список контактов можно получить с помощью команды getMailingListDataSet. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"deleteContacts", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "listID":270, "deleteID":[ 1, 2 ] }, "id":"1" } |
Результат вызова содержит число удаленных контактов или ошибку. |
{ "jsonrpc":"2.0", "result":{ "contactsDeleted":2 }, "id":1 } |
addMessage |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"addMessage", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "messageName":"New message from API", "subject":"RXhhbXBsZSBtZXNzYWdl", "messageType":"Html", "textPartMode":"ExtractFromHtml", "htmlPart":"PGh0bWw+PGhlYWQ+DQo8bWV0YSBjb250ZW50PSJ0ZXh0L2h0bWw7IGNoYXJzZXQ9LVtDSEFSU0VUXS0iIGh0dHAtZXF1aXY9Q29udGVudC1UeXBlPg0KPG1ldGEgbmFtZT1HRU5FUkFUT1IgY29udGVudD0iLVtPVVRMT09LX1ZFUl0tIj48L2hlYWQ+DQo8Ym9keSBib3R0b21NYXJnaW49NSBiZ0NvbG9yPSIjZmZmZmZmIiBsZWZ0TWFyZ2luPTUgdG9wTWFyZ2luPTUgcmlnaHRNYXJnaW49NT48Zm9udCBjb2xvcj0iIzAwMDAwMCIgc2l6ZT0yIGZhY2U9QXJpYWw+DQo8ZGl2PlRoaXMgaXMgYSBtZXNzYWdlIGJvZHkgd2l0aCBpbWFnZTwvZGl2Pg0KPGRpdj48aW1nIGJvcmRlcj0wIGhzcGFjZT0wIGFsdD0iIiBzcmM9Ik5ldHdvcmtJY29uLnBuZyIgd2lkdGg9MTYgaGVpZ2h0PTE2PjwvZGl2PjwvZm9udD48L2JvZHk+PC9odG1sPg0K", "textPart":"77u\/VGhpcyBpcyBhIG1lc3NhZ2UgYm9keSB3aXRoIGltYWdl", "priority":"Normal", "requestReadReceipt":false, "asIsMode":false, "charset":"utf-8", "contentTransferEncoding":"auto", "headerInlineEncdoing":"auto", "customHeaderLines":[ "X-My-Custom-Header-Field: My value", "List-Unsubscribe: <[%%TUnsubscribeLink,9,AE%%]>" ], "attachments":[ { "fileName":"ExampleAttachment.txt", "fileContent":"Q29udGVudCBvZiBhdHRhY2hlZCB0ZXh0IGZpbGU=" } ], "htmlAttachments":[ { "fileName":"NetworkIcon.png", "fileContent":"iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8\/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAg1JREFUeNqkU01rE1EUPS+Thnx0nBnTIlMXLgRFAkHp2q1uKqiUFMWVLgxUFPwPWetCF91kpe3OjwpVdwF3GiEE1JWtBktbJzNvzHwk0Xx43ziOSa246IXDu2\/eu+edc+c9NhwOsZ+IFwqF0fk5gv6fmi3Cs4hgdKXdbuvlcnnJcRx0Oh00mx5ct4dMZhLaQQ1T2SyKxYVFSZKwJ4GIXq8Hy7Jg2zZMy4NDBJqmIp5gUJTMX3KkXC43VlytVmcYY8cMw8DnTx\/RNL7gm70Dm2\/j+dqTl5zzh7FYbPNfCmZLpdJcZMFyYDttpDKpQMXcxYWzN4vXVmnf64hgMBhE1SIfs2A74J4HWZURSwwgK8lgDyn8Y0HX9eA0Ad\/3Wa1WO0xN+mVhYx3W1214nMO1ONaerr5oNBor3W5383cNy+fzoz24ValU7kYWeAumayORjkPVFGTpT8yfOX+bFNyJLNTr9SBJJpPUZUUes9BqwfA5MmoSTFg4kIJpmrJYEweIYCMNPEIk83QzD\/X7\/WCN8pnApyRtUeeHofcdui+PaFzfTaASUtG3XAJ49\/1GmN+jfOzOEfhugvFYnl7Chx+zQX5i4i0uG9f3fAuEKcJRwknCKcJxgoxlFxfKlwKCx1dXxFAlCG8bYf6G8F4omAilT4ZIC9tYTF\/BNDsdHGMMX+G+\/2BEvhPCZ\/t9zj8FGAAyaftHYMhilQAAAABJRU5ErkJggg==" } ], "trackingOptions":{ "openTracking":true, "clicksTracking":true, "trackingMethod":"AmswebOnly", "amswebLinkID":9, "amswebLinkUsageMode":"selectAmswebLinkBySenderDomain", "utmParams":{ "utmMedium":"email", "utmSource":"AMS Enterprise", "utmCampaign":"[%%MailingName%%]", "utmContent":"[%%MessageName%%]" } } }, "id":"1" } |
||
Результат вызова содержит ID созданного письма рассылки или ошибку: |
||
{ "jsonrpc":"2.0", "result":{ "newResourceID":21 }, "id":1 } |
editMessage |
Команда редактирует письмо.
Описание параметров:
apiKey - ключ доступа к API
id - id письма, которое нужно отредактировать. Обязательный параметр. Получить список имеющихся писем можно с помощью команды getMessages.
Все остальные параметры могут быть такими же как и у команды addMessage, но не обязательно передавать их все если нужно изменить только какую-то конкретную настройку. Например, если вы хотите только изменить тему письма - достаточно будет subject и больше ничего. Те объекты, которые не передавались в параметрах команды - останутся без изменений. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"editMessage", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":1, "messageName":"New subject from API", "subject":"RXhhbXBsZSBtZXNzYWdl", "messageType":"Html", "textPartMode":"ExtractFromHtml", "htmlPart":"PGh0bWw+PGhlYWQ+DQo8bWV0YSBjb250ZW50PSJ0ZXh0L2h0bWw7IGNoYXJzZXQ9LVtDSEFSU0VUXS0iIGh0dHAtZXF1aXY9Q29udGVudC1UeXBlPg0KPG1ldGEgbmFtZT1HRU5FUkFUT1IgY29udGVudD0iLVtPVVRMT09LX1ZFUl0tIj48L2hlYWQ+DQo8Ym9keSBib3R0b21NYXJnaW49NSBiZ0NvbG9yPSIjZmZmZmZmIiBsZWZ0TWFyZ2luPTUgdG9wTWFyZ2luPTUgcmlnaHRNYXJnaW49NT48Zm9udCBjb2xvcj0iIzAwMDAwMCIgc2l6ZT0yIGZhY2U9QXJpYWw+DQo8ZGl2PlRoaXMgaXMgYSBtZXNzYWdlIGJvZHkgd2l0aCBpbWFnZTwvZGl2Pg0KPGRpdj48aW1nIGJvcmRlcj0wIGhzcGFjZT0wIGFsdD0iIiBzcmM9Ik5ldHdvcmtJY29uLnBuZyIgd2lkdGg9MTYgaGVpZ2h0PTE2PjwvZGl2PjwvZm9udD48L2JvZHk+PC9odG1sPg0K", "textPart":"77u\/VGhpcyBpcyBhIG1lc3NhZ2UgYm9keSB3aXRoIGltYWdl", "priority":"Normal", "requestReadReceipt":false, "asIsMode":false, "charset":"utf-8", "contentTransferEncoding":"auto", "customHeaderLines":[ "X-My-Custom-Header-Field: My value", "List-Unsubscribe: <[%%TUnsubscribeLink,9,AE%%]>" ], "attachments":[ { "fileName":"ExampleAttachment.txt", "fileContent":"Q29udGVudCBvZiBhdHRhY2hlZCB0ZXh0IGZpbGU=" } ], "htmlAttachments":[ { "fileName":"NetworkIcon.png", "fileContent":"iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8\/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAg1JREFUeNqkU01rE1EUPS+Thnx0nBnTIlMXLgRFAkHp2q1uKqiUFMWVLgxUFPwPWetCF91kpe3OjwpVdwF3GiEE1JWtBktbJzNvzHwk0Xx43ziOSa246IXDu2\/eu+edc+c9NhwOsZ+IFwqF0fk5gv6fmi3Cs4hgdKXdbuvlcnnJcRx0Oh00mx5ct4dMZhLaQQ1T2SyKxYVFSZKwJ4GIXq8Hy7Jg2zZMy4NDBJqmIp5gUJTMX3KkXC43VlytVmcYY8cMw8DnTx\/RNL7gm70Dm2\/j+dqTl5zzh7FYbPNfCmZLpdJcZMFyYDttpDKpQMXcxYWzN4vXVmnf64hgMBhE1SIfs2A74J4HWZURSwwgK8lgDyn8Y0HX9eA0Ad\/3Wa1WO0xN+mVhYx3W1214nMO1ONaerr5oNBor3W5383cNy+fzoz24ValU7kYWeAumayORjkPVFGTpT8yfOX+bFNyJLNTr9SBJJpPUZUUes9BqwfA5MmoSTFg4kIJpmrJYEweIYCMNPEIk83QzD\/X7\/WCN8pnApyRtUeeHofcdui+PaFzfTaASUtG3XAJ49\/1GmN+jfOzOEfhugvFYnl7Chx+zQX5i4i0uG9f3fAuEKcJRwknCKcJxgoxlFxfKlwKCx1dXxFAlCG8bYf6G8F4omAilT4ZIC9tYTF\/BNDsdHGMMX+G+\/2BEvhPCZ\/t9zj8FGAAyaftHYMhilQAAAABJRU5ErkJggg==" } ], "trackingOptions":{ "openTracking":true, "clicksTracking":true, "trackingMethod":"AmswebOnly", "amswebLinkID":9, "amswebLinkUsageMode":"selectAmswebLinkBySenderDomain", "utmParams":{ "utmMedium":"email", "utmSource":"AMS Enterprise", "utmCampaign":"[%%MailingName%%]", "utmContent":"[%%MessageName%%]" } } }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
deleteMessage |
Команда удаляет письмо.
Описание параметров:
apiKey - ключ доступа к API.
id - id письма которое нужно удалить, обязательный параметр. Получить список имеющихся писем можно с помощью команду getMessages |
Пример вызова:
{ "jsonrpc":"2.0", "method":"deleteMessage", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":6 }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
getMessages |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"getMessages", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875" }, "id":"1" } |
||
Результат вызова содержит массив имеющихся писем.
id - id письма.
subject - тема письма.
messageName - имя письма.
messageType - тип письма. Html или Text.
openTracking - для письма разрешено отслеживание открытий.
clicksTracking - для письма разрешено отслеживание кликов. |
||
{ "jsonrpc":"2.0", "result":[ { "id":1, "subject":"Example message", "messageName":"New message from API", "messageType":"Html", "openTracking":false, "clicksTracking":true }, { "id":7, "subject":"Weekly newsletter", "messageName":"my site news", "messageType":"Html", "openTracking":false, "clicksTracking":false } ], "id":1 } |
getMessage |
Команда возвращает подробную информацию о письме.
Описание параметров:
apiKey - ключ доступа к API
id - id письма, данные о котором нужно получить. Список имеющихся писем можно получить с помощью команды getMessages. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"getMessage", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":1 }, "id":"1" } |
Результат вызова содержит объект с информацией о письме. Вы можете использовать полученный объект как образец для создания или редактирования писем (см. команды addMessage и editMessage).
id - id письма.
messageName - имя письма (не участвует в рассылке, используется только для удобства выбора нужного письма из множества писем с одинаковой темой).
subject - тема (subject) письма.
messageType - тип письма. Возможные значения:
Html - тип письма html, так же для письма может быть задана и текстовая часть (multipart/alternative), см. параметр textPartMode Text - тип письма текст (plain text без html части). Значение по умолчанию - Html. textPartMode - определяет способ формирования текстовой части для html писем. Возможные значения:
ExtractFromHtml - автоматически сформировать текстовую часть путем извлечения текста из html части CustomTextPart - задать свою текстовую часть, текст которой будет отличаться от html части. NoTextPart - отключить текстовую часть, в этом случае типа письма будет text/html вместо multipart/alternative.
htmlPart - содержимое Html части письма. Это должен быть Html код в кодировке UTF-8 (желательно чтобы html код содержал META тэг с указанием кодировки). Html код должен передаваться в виде строки закодированной в base64.
textPart - текстовая часть письма. Должна быть в кодировке UTF-8 и передаваться в виде строки, закодированной в base64. Значение параметра должно быть задано если messageType=Text или textPartMode=CustomTextPart.
priority - приоритет письма (значение для поля заголовка X-Priority). Возможные значения: Low, Normal, High. По умолчанию - Normal
requestReadReceipt - если true - добавить в заголовок письма запрос уведомления о прочтении (поле Disposition-Notification-To:). В запросе будет использован обратный (From:) email. Значение по умолчанию false.
asIsMode - если true для письма будет включен режим "как есть" сохраняющий исходное форматирование. При открытии такого письма в редакторе не будет производится преобразование его кода во внутреннее представление редактора (которое может немного изменить его изначальный html код), при этом в редакторе не будет доступно визуальное редактирование письма (редактирование будет возможно только на вкладке Исходный код).
charset - желаемая кодировка письма, рекомендуется использовать значение по умолчанию utf-8.
contentTransferEncoding - выбор транспортной кодировки для html и текстовых частей письма. Возможные значения:
auto - автоматический выбор наилучшего варианта в зависимости от типа письма, в большинстве случаев это quoted-printable. Значение по умолчанию. quoted-printable - использовать кодировку quoted-printable base64 - использовать кодировку base64.
headerInlineEncoding - выбор inline кодировки для полей заголовка письма, содержащих non-ascii символы. Возможные значения:
auto - автоматический выбор наилучшего варианта в зависимости от типа письма, в большинстве случаев это base64. Значение по умолчанию. quoted-printable - использовать кодировку quoted-printable base64 - использовать кодировку base64.
customHeaderLines - массив пользовательских строк, которые будут добавлены в конец служебного заголовка письма.
attachments - массив, в котором передаются вложения.
fileName - имя приложенного файла. fileContent - содержимое приложенного файла. Должно быть закодировано в base64.
htmlAttachments - если письмо содержит встроенные картинки - они передаются в этом массиве.
fileName - имя файла картинки. Например, если html код содержит фрагмент c описаниеv картинки <img src="NetworkIcon.png"> то fileName должен быть NetworkIcon.png fileContent - содержимое файла картинки. Должно быть закодировано в base64
trackingOptions - объект содержит настройки по отслеживанию открытия письма и кликам по ссылкам в письме.
openTracking - если true разрешает отслеживание открытий письма.
clicksTracking - если true разрешает отслеживание кликов по ссылкам в письме.
trackingMethod - способ отслеживания кликов. Возможные значения:
AmswebOnly - используется только штатный механизм статистики AMS через скрипт amsweb.php. Значение по умолчанию.
UtmOnly - используется только Google analytics и/или Яндекс-метрика (ко всем ссылкам в письме добавляются utm метки).
AmswebAndUtm - используется оба метода сразу - к ссылкам добавляются utm метки, при этом клик происходит через штатный скрипт AMS amsweb.php
amswebLinkID - id ссылки на скрипт amsweb.php, которая будет использоваться для сбора статистики для этого письма. Получить список имеющихся ссылок можно с помощью команды getAmswebLinks.
amswebLinkUsageMode - режим выбора ссылки на скрипт amsweb.php. Возможные значения:
useAmswebLinkID - использовать ссылку, заданную в параметре trackingOptions.amswebLinkID selectAmswebLinkBySenderDomain - пытаться выбрать ссылку на amsweb.php чей домен совпадает с доменом from адреса. Например, если обратный адрес это info@domain.com то будет выбрана ссылка на скрипт http://domain.com/amsweb.php. Если подходящую ссылку найти не удастся - будет использована ссылка, заданная в параметре trackingOptions.amswebLinkID useRandomAmswebLink - для каждого письма будет выбираться случайная ссылка на amsweb.php из имеющихся.
utmParams - объект в котором задаются utm метки если trackingOptions.trackingMethod равен UtmOnly или AmswebAndUtm. Информацию о назначении utm меток смотрите в спарвке по google analytics и яндекс-метрике. |
{ "jsonrpc":"2.0", "result":{ "id":1, "messageName":"New message from API", "subject":"RXhhbXBsZSBtZXNzYWdl", "messageType":"Html", "textPartMode":"ExtractFromHtml", "htmlPart":"PGh0bWw+PGhlYWQ+DQo8bWV0YSBjb250ZW50PSJ0ZXh0L2h0bWw7IGNoYXJzZXQ9LVtDSEFSU0VUXS0iIGh0dHAtZXF1aXY9Q29udGVudC1UeXBlPg0KPG1ldGEgbmFtZT1HRU5FUkFUT1IgY29udGVudD0iLVtPVVRMT09LX1ZFUl0tIj48L2hlYWQ+DQo8Ym9keSBib3R0b21NYXJnaW49NSBiZ0NvbG9yPSIjZmZmZmZmIiBsZWZ0TWFyZ2luPTUgdG9wTWFyZ2luPTUgcmlnaHRNYXJnaW49NT48Zm9udCBjb2xvcj0iIzAwMDAwMCIgc2l6ZT0yIGZhY2U9QXJpYWw+DQo8ZGl2PlRoaXMgaXMgYSBtZXNzYWdlIGJvZHkgd2l0aCBpbWFnZTwvZGl2Pg0KPGRpdj48aW1nIGJvcmRlcj0wIGhzcGFjZT0wIGFsdD0iIiBzcmM9Ik5ldHdvcmtJY29uLnBuZyIgd2lkdGg9MTYgaGVpZ2h0PTE2PjwvZGl2PjwvZm9udD48L2JvZHk+PC9odG1sPg0K", "textPart":"77u\/VGhpcyBpcyBhIG1lc3NhZ2UgYm9keSB3aXRoIGltYWdl", "priority":"Normal", "requestReadReceipt":false, "asIsMode":false, "charset":"utf-8", "contentTransferEncoding":"auto", "headerInlineEncdoing":"auto", "customHeaderLines":[ "X-My-Custom-Header-Field: My value", "List-Unsubscribe: <[%%TUnsubscribeLink,9,AE%%]>" ], "attachments":[ { "fileName":"ExampleAttachment.txt", "fileContent":"Q29udGVudCBvZiBhdHRhY2hlZCB0ZXh0IGZpbGU=" } ], "htmlAttachments":[ { "fileName":"NetworkIcon.png", "fileContent":"iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8\/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAg1JREFUeNqkU01rE1EUPS+Thnx0nBnTIlMXLgRFAkHp2q1uKqiUFMWVLgxUFPwPWetCF91kpe3OjwpVdwF3GiEE1JWtBktbJzNvzHwk0Xx43ziOSa246IXDu2\/eu+edc+c9NhwOsZ+IFwqF0fk5gv6fmi3Cs4hgdKXdbuvlcnnJcRx0Oh00mx5ct4dMZhLaQQ1T2SyKxYVFSZKwJ4GIXq8Hy7Jg2zZMy4NDBJqmIp5gUJTMX3KkXC43VlytVmcYY8cMw8DnTx\/RNL7gm70Dm2\/j+dqTl5zzh7FYbPNfCmZLpdJcZMFyYDttpDKpQMXcxYWzN4vXVmnf64hgMBhE1SIfs2A74J4HWZURSwwgK8lgDyn8Y0HX9eA0Ad\/3Wa1WO0xN+mVhYx3W1214nMO1ONaerr5oNBor3W5383cNy+fzoz24ValU7kYWeAumayORjkPVFGTpT8yfOX+bFNyJLNTr9SBJJpPUZUUes9BqwfA5MmoSTFg4kIJpmrJYEweIYCMNPEIk83QzD\/X7\/WCN8pnApyRtUeeHofcdui+PaFzfTaASUtG3XAJ49\/1GmN+jfOzOEfhugvFYnl7Chx+zQX5i4i0uG9f3fAuEKcJRwknCKcJxgoxlFxfKlwKCx1dXxFAlCG8bYf6G8F4omAilT4ZIC9tYTF\/BNDsdHGMMX+G+\/2BEvhPCZ\/t9zj8FGAAyaftHYMhilQAAAABJRU5ErkJggg==" } ], "trackingOptions":{ "openTracking":true, "clicksTracking":true, "trackingMethod":"AmswebOnly", "amswebLinkID":9, "amswebLinkUsageMode":"selectAmswebLinkBySenderDomain", "utmParams":{ "utmMedium":"email", "utmSource":"AMS Enterprise", "utmCampaign":"[%%MailingName%%]", "utmContent":"[%%MessageName%%]" } } }, "id":1 } |
addDeliveryPreset |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"addDeliveryPreset", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "name":"Example preset", "deliveryMode":"RelaysOnly", "commonOptions":{ "dnsResolverAttempts":2, "sendingAttempts":3, "netTimeout":60, "maxMessagesPerSmtpSession":2, "sendingMethod":"PersonalCopy", "useProxy":false, "proxyListID":1, "advancedProxyOptions":{ "maxThreadsPerProxy":0, "proxyRotationOptions":{ "enableProxyRotation":false, "rotationPoolSize":10, "rotationPoolSwitchInterval":100, "syncProxyRotationWithRelaysRoation":false, "restartSyncRotationIfAllProxiesUsed":false }, "proxyAutoExclusionOptions":{ "enableAutoExclusion":false, "proxyExclusionMode":"ByNumberOfFailedConnections", "proxyExclusionValue":50, "proxyExclusionTime":20 } }, "useMultiHomeIP":false, "muiltiHomeIpList":[ { "ip":"192.168.1.21", "hostName":"mail.domain.com", "comment":"", "enabled":true }, { "ip":"192.168.122.1", "hostName":"", "comment":"", "enabled":true } ], "heloMode":"Default", "customHelo":"[%%ORandText,HeloStrings%%]", "globalSpeedThrottle":{ "throttleEnabled":false, "msgNumber":10, "perSeconds":60 } }, "relaysOptions":{ "relaysList":[ { "enabled":true, "uniqID":"9TMdmnerZUeOpRSdm_lhKA", "primaryOptions":{ "serverName":"smtp.mailserver.com", "port":25, "threads":3, "bccSize":10, "authOptions":{ "enableAuthentication":true, "authType":"Auto", "login":"from@mailserver.com", "password":"mailboxpass", "useLoginAsFromEmail":true }, "sslOptions":{ "sslEnabled":true, "sslMode":"Auto" }, "throttleOptions":{ "throttleEnabled":false, "msgNumber":25, "perSeconds":120 } }, "additionalOptions":{ "socksRelayLink":"", "customHelo":"", "customFromName":"", "comment":"", "customMsgBodyFileName":"" }, "speedThrottleListForTargetDomains":[ { "domainName":"gmail.com", "throttleOptions":{ "msgNumber":100, "perMinutes":5 } } ] } ], "advancedRelaysOptions":{ "relaysResendingOptions":{ "enableResendViaRandomRelay":false, "resendViaRandomRelayAttempts":2, "enableResendViaBuiltInServer":false, "resendViaBuiltInServerAttempts":2 }, "relaysAutoExclusionOptions":{ "enableAutoExclusion":true, "excludeOnErrorsCount":5, "excludeForSeconds":300, "markRelayAsBadOnExclusionOrAuthErrors":true }, "relaysRotationOptions":{ "enableRelaysRotation":false, "rotationPoolSize":3, "rotationPoolSwitchInterval":20 }, "alwaysUseRelaysForDomains":[ "domain1.com" ] }, "relaysSpeedThrottleForTargetDomains":{ "domainsThrottleUsageMode":"ShareBetweenRelays", "domainsThrottleList":[ { "domainName":"hotmail.com", "throttleOptions":{ "msgNumber":100, "perMinutes":10 } } ] } }, "builtInServerOptions":{ "builtInServerThreads":100, "maxBccSize":10, "maxThreadsPerTargetDomain":0, "builtInServerResendingOptions":{ "enableResendViaRandomRelayOnErrors":false, "resendViaRandomRelayAttempts":2 }, "alwaysUseBuiltInServerForDomains":[ "domain2.com" ], "builtInServerTargetDomainsThrottleList":[ { "domainName":"yahoo.com", "limitSendingThreads":true, "maxSendingThreads":3, "throttleOptions":{ "throttleEnabled":true, "msgNumber":100, "perMinutes":10 } } ] } }, "id":"1" } |
||
Результат вызова содержит ID созданного профиля отправки или ошибку: |
||
{ "jsonrpc":"2.0", "result":{ "newResourceID":21 }, "id":1 } |
editDeliveryPreset |
Команда редактирует профиль отправки.
Поскольку объект профиля отправки довольно сложный - вы можете вначале получить json представление профиля отправки с помощью команды getDeliveryPreset, внести необходимые изменения, после чего передать измененный профиль в команду editDeliveryPreset.
Описание параметров:
apiKey - ключ доступа к API
id - id профиля отправки, который нужно отредактировать. Обязательный параметр. Получить список имеющихся профилей отправки можно с помощью команды geDeliveryPresets.
Все остальные параметры могут быть такими же как и у команды addDeliveryPresets, но не обязательно передавать их все если нужно изменить только какую-то конкретную настройку. Например, если вы хотите только изменить список smtp серверов (или отредактировать отдельный smtp сервер) - достаточно передать только массив relaysOptions.relaysList. Обратите внимание, что даже если вы хотите отредактировать только один smtp сервер из имеющихся в профиле - вам нужно передавать массив со всеми smtp серверами, в том числе с отредактированным т.к. содержимое массива полностью перезаписывается новыми данными ! Это же касается и других массивов в объекте профиля - их содержимое полностью перезаписывается новыми данными. Те объекты, которые не передавались в параметрах команды - останутся без изменений. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"editDeliveryPreset", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":21, "name":"Renamed preset", "deliveryMode":"RelaysOnly", "commonOptions":{ "dnsResolverAttempts":2, "sendingAttempts":3, "netTimeout":60, "maxMessagesPerSmtpSession":2, "sendingMethod":"PersonalCopy", "useProxy":false, "proxyListID":1, "advancedProxyOptions":{ "maxThreadsPerProxy":0, "proxyRotationOptions":{ "enableProxyRotation":false, "rotationPoolSize":10, "rotationPoolSwitchInterval":100, "syncProxyRotationWithRelaysRoation":false, "restartSyncRotationIfAllProxiesUsed":false }, "proxyAutoExclusionOptions":{ "enableAutoExclusion":false, "proxyExclusionMode":"ByNumberOfFailedConnections", "proxyExclusionValue":50, "proxyExclusionTime":20 } }, "useMultiHomeIP":false, "muiltiHomeIpList":[
], "heloMode":"Default", "globalSpeedThrottle":{ "throttleEnabled":false, "msgNumber":10, "perSeconds":60 } }, "relaysOptions":{ "relaysList":[ { "enabled":true, "uniqID":"9TMdmnerZUeOpRSdm_lhKA", "primaryOptions":{ "serverName":"smtp.mailserver.com", "port":25, "threads":3, "bccSize":10, "authOptions":{ "enableAuthentication":true, "authType":"Auto", "login":"from@mailserver.com", "password":"mailboxpass", "useLoginAsFromEmail":true }, "sslOptions":{ "sslEnabled":true, "sslMode":"Auto" }, "throttleOptions":{ "throttleEnabled":false, "msgNumber":25, "perSeconds":120 } }, "additionalOptions":{ "socksRelayLink":"", "customHelo":"", "customFromName":"", "comment":"", "customMsgBodyFileName":"" }, "speedThrottleListForTargetDomains":[ { "domainName":"gmail.com", "throttleOptions":{ "msgNumber":100, "perMinutes":5 } } ] } ], "advancedRelaysOptions":{ "relaysResendingOptions":{ "enableResendViaRandomRelay":false, "resendViaRandomRelayAttempts":2, "enableResendViaBuiltInServer":false, "resendViaBuiltInServerAttempts":2 }, "relaysAutoExclusionOptions":{ "enableAutoExclusion":true, "excludeOnErrorsCount":5, "excludeForSeconds":300, "markRelayAsBadOnExclusionOrAuthErrors":true }, "relaysRotationOptions":{ "enableRelaysRotation":false, "rotationPoolSize":3, "rotationPoolSwitchInterval":20 }, "alwaysUseRelaysForDomains":[ "domain1.com" ] }, "relaysSpeedThrottleForTargetDomains":{ "domainsThrottleUsageMode":"ShareBetweenRelays", "domainsThrottleList":[ { "domainName":"hotmail.com", "throttleOptions":{ "msgNumber":100, "perMinutes":10 } } ] } }, "builtInServerOptions":{ "builtInServerThreads":100, "maxBccSize":10, "maxThreadsPerTargetDomain":0, "builtInServerResendingOptions":{ "enableResendViaRandomRelayOnErrors":false, "resendViaRandomRelayAttempts":2 }, "alwaysUseBuiltInServerForDomains":[ "domain2.com" ], "builtInServerTargetDomainsThrottleList":[ { "domainName":"yahoo.com", "limitSendingThreads":true, "maxSendingThreads":3, "throttleOptions":{ "throttleEnabled":true, "msgNumber":100, "perMinutes":10 } } ] } }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
deleteDeliveryPreset |
Команда удаляет профиль отправки.
Описание параметров:
apiKey - ключ доступа к API.
id - id профиля отправки, который нужно удалить, обязательный параметр. Получить список имеющихся профиле отправки можно с помощью команды getDeliveryPresets. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"deleteDeliveryPreset", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":20 }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
getDeliveryPresets |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"getDeliveryPresets", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875" }, "id":"1" } |
||
Результат вызова содержит массив с краткой информацией об имеющихся профилях отправки:
id - id профиля отправки
name - имя профиля отправки.
sendingMethod - метод рассылки, выбранный для этого профиля. Возможные значения: To, Cс, Bcc, PersonalCopy
deliveryMode - режим рассылки, выбранный для этого профиля. Возможные значения:
RelaysOnly - отправка только внешние smtp серверы (релеи). RelaysAndBuiltInServerOnErrors - вначале попытка отправить через внешние smtp релеи, а в случае ошибки доставки попробовать отправить через встроенный smtp сервер AMS. BuiltInServerAndRelaysOnErrors - вначале попытка отправить через встроенный smtp сервер, в случае не удачи попробовать через внешние smtp серверы (релеи). BuiltInServerOnly - отправка только встроенный Smtp сервер AMS.
proxyUsed - если true то для рассылки используются прокси.
sendingThreads - число потоков отправки (параллельных соединений), которые будут использованы при рассылке через этот профиль отправки. |
||
{ "jsonrpc":"2.0", "result":[ { "id":18, "name":"Example preset", "sendingMethod":"PersonalCopy", "deliveryMode":"RelaysOnly", "proxyUsed":false, "sendingThreads":1 }, { "id":20, "name":"Another preset", "sendingMethod":"PersonalCopy", "deliveryMode":"BuiltInServerOnly", "proxyUsed":false, "sendingThreads":30 } ], "id":1 } |
getDeliveryPreset |
Команда возвращает подробную информацию о профиле отправки.
Описание параметров:
apiKey - ключ доступа к API
id - id профиля отправки, чье json представление нужно получить. Обязательный параметр. Получить список имеющихся профилей отправки можно с помощью команды getDeliveryPresets |
Пример вызова:
{ "jsonrpc":"2.0", "method":"getDeliveryPreset", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":18 }, "id":"1" } |
Результат вызова содержит json представление объекта профиля отправки или ошибку. Вы можете использовать полученное представление как образец для создания новым профилей или для редактирования настроек имеющихся профилей:
id - id профиля отправки.
name - имя профиля отправки.
deliveryMode - режим рассылки. Возможные значения:
RelaysOnly - отправка только через внешние smtp серверы (релеи). RelaysAndBuiltInServerOnErrors - вначале попытка отправить через внешние smtp релеи, а в случае ошибки доставки попробовать отправить через встроенный smtp сервер AMS. BuiltInServerAndRelaysOnErrors - вначале попытка отправить через встроенный smtp сервер, в случае не удачи попробовать через внешние smtp серверы (релеи). BuiltInServerOnly - отправка только встроенный Smtp сервер AMS.
commonOptions - объект, который содержит общие настройки профиля для всех режимов рассылки:
dnsResolverAttempts - число попыток получить MX и A записи через DNS запросы.
sendingAttempts - число попыток отправить письмо.
netTimeout - сетевой таймаут соединения (в секундах).
maxMessagesPerSmtpSession - число писем, которые будут отправлены в рамках одного подключения к smtp серверу (отправка последовательности писем разделяется Smtp командой RSET).
sendingMethod - метод рассылки. Возможные значения: To, Cc, Bcc, PersonalCopy.
useProxy - если true то использовать прокси для рассылки.
proxyListID - id списка прокси, который будет использоваться для рассылки. Обязателен если useProxy=true. Получить список имеющихся списков прокси можно с помощью команды getProxyLists.
advancedProxyOptions - объект содержит настройки по авто-отключению и ротации прокси:
maxThreadsPerProxy - максимальное число потоков отправки (параллельных соединений), которые могут быть использованы через каждый прокси. Если 0 - ограничения нет.
proxyRotationOptions - объект с настройками ротации прокси:
enableProxyRotation - если true то ротация включена.
rotationPoolSize - размер пула ротации. Т.е. сколько прокси (из числа доступных) будут использоваться в ротации.
rotationPoolSwithInterval - число писем после обработки которых прокси уходит из пула ротации, а вместо него в пул попадает новый прокси. Под обработкой понимается попытка отправить письмо без учета результата отправки.
syncProxyRotationWithRelaysRotation - с помощью этого параметра можно автоматически связать каждый smtp сервер с одним и только одним прокси сервером. Таким образом, для каждого smtp сервера соединение будет приходить только с одного и того же "своего" прокси. Обратите внимание, что связка действует до конца рассылки ! После перезапуска рассылки для smtp сервера может быть выбран другой прокси.
restartSyncRotationIfAllProxiesUsed - если параметр syncProxyRotationWithRelaysRotation=true И при этом число прокси меньше чем число smtp серверов - в какой-то момент для очередного smtp сервера уже не найдется свободного прокси, не связанного с другим smtp сервером. В этом случае формирование связок прокси<->Smtp сервер начнется заново начиная с smtp сервера, для которого не нашлось свободного прокси.
proxyAutoExclusionOptions - объект содержит настройки по автоматическому исключению прокси из рассылок в случае множества ошибок отправки:
enableAutoExclusion - если true то прокси будет исключаться из рассылки в случае если через него стали плохо отправляться письма.
proxyExclusionMode - режим автоматического исключения прокси. Возможные значения:
ByNumberOfFailedConnections - прокси будет исключен из рассылки если число неудачных попыток соединений подряд превысило заданное значение.
ByNumberOfUnsentMsgInRow - прокси будет исключен из рассылки если число не отправленных подряд писем превысило заданное значение.
ByProxyEffeciency - прокси будет исключен из рассылки если его эффективность (% удачных соединений) стало ниже заданного процента.
proxyExclusionValue - в зависимости от значения параметра proxyExclusionMode - число не удачных соединений подряд, число не отправленных писем подряд или % эффективности прокси при достижении которого прокси будет исключен из рассылки.
proxyExclusionTime - время (в минутах) на которое прокси будет исключен из рассылки. Если значение 0 - прокси будет исключен до остановки рассылки.
useMultiHomeIP - если AMS установлен на сервер, имеющего множество IP адресов - можно выбрать какие IP будут использован для рассылки. Если true - разрешено использовать заданные IP адреса.
multiHomeIpList - массив со списком локальных IP, с которых разрешена отправка писем.
multiHomeIpList.ip - локальный ip адрес, который будет использован для рассылки.
multiHomeIpList.hostName - имя хоста (значение PTR записи, привязанной к IP). Если значение задано - оно может быть использовано в smtp команде EHLO. См. описание параметра heloMode ниже.
multiHomeIpList.comment - любой пользовательский комментарий (строка). Во время рассылки может быть подставлен в любое место тела или заголовка письма с помощью макроса [%%PMultiHomeIPComment%%]
heloMode - режим формирования строки с именем хоста для команды Smtp HELO/EHLO. Возможные значения:
Default - используется значение HELO по умолчанию - это имя компьютера, на котором установлен AMS, или глобальное значение HELO, заданное в окне Настройки->Доп. Настройки.
UseProxyHosts - если разрешена рассылка через прокси - будут использоваться имена хостов прокси (содержимое поля Host в списки прокси).
UseRelaysHelo - если рассылка через внешние smtp серверы - будет использовано индивидуальное helo, заданное для каждого smtp сервера, см. параметр relaysOptions.relaysList.additionalOptions.customHelo.
UseMultiHomeIPHosts - если разрешена отправка с заданных локальных IP адресов - будет использовано имя хоста, связанного с IP адресом, см параметр multiHomeIpList.hostName.
Custom - значение для HELO задает пользователь. Зачастую он формируется макросами [%%ORandStr%%], [%%ORandText%%] и другими.
customHelo - если heloMode=Custom - в этом параметре передается пользовательское значение HELO для профиля отправки.
globalSpeedThrottle - объект содержит настройки глобального ограничения скорости рассылки.
throttleEnabled - если true то глобальное ограничение скорости рассылки включено.
msgNumber - число писем, после отправки которых программа приостановит рассылку на заданное время.
perSeconds - число секунд, на которые будет приостановлена рассылки после отправки числа писем, заданных в параметре msgNumber.
relaysOptions - объект содержит список smtp серверов а так же настройки рассылки через релеи:
relaysList - массив с smtp серверами, которые будут использоваться для рассылки этим профилем отправки:
enabled - smtp сервер включен.
uniqID - уникальный идентификатор smtp сервера. Уникальность и обработку этих ID выполняет AMS ! Никогда не задавайте и не меняйте значения этого поля.
primaryOptions - объект с основными настройками smtp сервера:
serverName - имя smtp сервера.
port - номер порта smtp сервера
threads - число потоков рассылки (параллельных соединений) через этот smtp сервер.
bccSize - размер BCC пакета т.е. число получателей для одного тела письма если sendingMethod = To или Cc или Bcc.
authOptions - объект содержит настройки авторизации для прокси сервера:
enableAuthentication - если true то авторизация включена, в противном случае программа не будет отправлять команду smtp AUTH.
authType - тип авторизации. Рекомендуемое значение Auto - в этом случае будет выбран оптимальный способ авторизации в зависимости от содержимого ответа smtp сервера на команду EHLO. Так же есть возможность задать в качестве типа авторизации одно из этих значений Auth-plain, Auth-login, Auth-cram-md5, Auth-cram-sha1, Auth-ntlm.
login - логин для smtp сервера.
password - пароль для smtp сервера.
useLoginAsFromEmail - использовать логин smtp сервера как обратный адрес при рассылке. По умолчанию включено т.к. почти всегда почтовые сервера требуют чтобы логин и обратный адрес совпадали. Если логин smtp сервера не в ввиде email адреса, но вы хотите задать нужный вам обратный адрес для smtp сервера - укажите этот адрес в логине, отделив его от логина тремя двоеточиями. Например, pmtauser:::from@mydomain.com
sslOptions - объект содержит настройки защищенного SSL/TLS соединения:
sslEnabled - если true то защищенное соединение включено.
sslMode - режим защищенного соединения. Возможные значения:
Auto - режим выбирается автоматически в зависимости от номера порта smtp сервера. Рекомендуемое значение.
SslConnection - устанавливается защищенное соединение, обычно если номер порта 465.
StartTls - вначале устанавливается обычное соединение, а потом переводится в защищенное с помощью команды smtp STARTTLS. Обычно если номер порта 25 или 587.
throttleOptions - объект содержит настройки ограничения скорости отправки через этот smtp сервер.
throttleEnabled - если true то ограничение скорости включено.
msgNumber - максимальное число писем, которые могут быть отправлены за указанное время.
perSeconds - число секунд за которые может быть отправлено не больше писем, чем указано в параметре msgNumber.
additionalOptions - объект с дополнительными настройками smtp сервера:
socksRelayLink - с помощью этого параметра вы можете жестко связать smtp сервер с некоторым прокси сервером. В качестве значения можно передать IP адрес прокси - 1.1.1.1 или IP:Port - 1.1.1.1:1080 или маску прокси 1.1.1.* - если указана маска - будет выбран случайный прокси из числа подходящих под маску. Чтобы связка работала - должна быть разрешена рассылка через прокси - commonOptions.useProxy=true и выбранный список прокси должен содержать прокси чей IP или IP:Port вы указали.
customHelo - в этом параметре можно задать строку для smtp команды HELO, которая будет использоваться только с этим smtp сервером. Обратите внимание, что при этом параметр commonOptions.heloMode должен содержать значение UseRelaysHelo.
customFromName - в этом параметре можно задать имя отправителя, которое будет использоваться только с этим smtp сервером и переопределит значение, заданное в Учетной записи отправителя.
comment - любой пользовательский комментарий (строка), привязанный к этому smtp серверу. Во время рассылки значение комментария может быть подставлено в любое место тела или заголовка письма с помощью макроса [%%PSmtpServerComment%%]
customMsgBodyFileName - для каждого smtp сервера можно задать свое тело письма. В этом параметре задается имя файла c телом письма, например MyRelayBody1.html. При этом папка, в которой выполняется поиск указанного файла задается в редакторе писем с помощью макроса [%%OMessageBodyByRelay%%]
advancedRelaysOptions - объект содержит дополнительные настройки, общие для режима отправки через smtp сервера:
relaysResendingOptions - объект содержит настройки по переотправке письма через другой smtp сервер в случае каких-либо ошибок:
enableResendViaRandomRelay - если true то в случае ошибок доставки программа попытается повторно отправить письмо через любой случайный smtp сервер из перечня доступных.
resendViaRandomRelayAttempts - число попыток переотправить письмо через случайный smtp сервер. Для каждой попытки выбирается новый случайный smtp сервер из перечня доступных.
enableResendViaBuiltInServer - если true то в случае ошибок отправки программа попытается переотправить письмо через встроенный smtp сервер. Для работы этой опции параметр deliveryMode должен содержать RelaysAndBuiltInServerOnErrors.
resendViaBuiltInServerAttempts - число попыток переотправить письмо через встроенный smtp сервер.
relaysAutoExclusionMode - объект содержит настройки по автоматическому исключению smtp сервера из рассылки в случае множества ошибок доставки:
enableAutoExclusion - если true то авто исключение smtp серверов включено.
excludeOnErrorsCount - число ошибок отправки подряд после которых smtp сервер будет исключен из рассылки.
excludeForSeconds - число секунд на которые smtp сервер будет исключен из рассылки.
markRelayAsBadOnExclusionOrAuthErrors - если true и во время рассылки smtp сервер выдал ошибку авторизации или был исключен из рассылки из-за множества ошибок - он будет помечен как "Плохой" и отключен в профиле отправки. В результате при следующем запуске рассылки данный smtp сервер в нее не попадет пока не будет снова включен пользователем в профиле отправки.
relaysRotationOptions - объект содержит настройки ротации smtp серверов.
enableRelaysRotation - если true то ротация smtp серверов включена.
rotationPoolSize - размер пула ротации. Т.е. сколько smtp серверов (из числа доступных) будут использоваться в ротации.
rotationPoolSwitchInterval - число писем после обработки которых smtp сервер уходит из пула ротации, а вместо него в пул попадает новый smtp сервер. Под обработкой понимается попытка отправить письмо без учета результата отправки.
alwaysUseRelaysForDomains - массив с доменами, письма на которые будут отправляться только через smtp сервера в случае если используется смешанный режим рассылки т.е. параметр deliveryMode содержит RelaysAndBuiltInServerOnErrors или BuiltInServerAndRelaysOnErrors.
relaysSpeedThrottleForTargetDomains - объект содержит настройки скоростных ограничений рассылки на заданные домены получателей (например, на @gmail.com и @hotmai.com отправлять медленнее чем на остальные домены в списке рассыкли).
domainsThrottleUsageMode - режим ограничения скорости. Возможные значения:
ShareBetweenRelays - заданные лимиты для целевых доменов являются общими для всех smtp серверов в профиле отправки. Т.е. через ВСЕ smtp сервера нельзя отправлять быстрее чем задано. IndividualPerRelay - каждый smtp сервер работает со своей копией скоростных лимитов для целевых доменов. Т.е. через КАЖДЫЙ smtp сервер нельзя отправлять быстрее чем задано.
domainsThrottleList - массив содержит домены получателей и настройки по скоростным лимитам для каждого домена.
domainName - имя домена получателя для которого нужно ограничить скорость отправки.
throttleOptions - объект с настройкой скоростного лимита для указанного домена:
msgNumber - максимальное число писем, которые могут быть отправлены за указанное время.
perMinutes - число минут за которые может быть отправлено не больше писем, чем указано в параметре msgNumber
builtInServerOptions - объект содержит настройки отправки через встроенный smtp сервер:
builtInServerThreads - число потоков отправки через встроенный smtp сервер.
maxBccSize - размер BCC пакета т.е. число получателей для одного тела письма если sendingMethod = To или Cc или Bcc.
maxThreadsPerTargetDomain - максимальное число потоков на MX серверы целевых доменов. Например, если ваш список рассылки содержит адреса только от 2-3 доменов (gmail.com, hotmail.com, yahoo.com) - то при использовании 150-200 потоков отправки вы будете получать ошибки вида "to may connections from IP" т.к. MX сервера могут содержать лимиты на максимальное число одновременных подключений с одного IP адреса. С помощью этого параметра вы можете ограничить максимальное число одновременных подключений для ВСЕХ доменов получателей. Если значение параметра 0 - ограничения нет.
builtInServerResendingOptions - объект содержит настройки переотправки писем через внешние smtp серверы если отправить через встроенный smtp сервер не удалось из-за каких-либо ошибок. Настройка принимается во внимание только если deliveryMode=BuiltInServerAndRelaysOnErrors.
enableResendViaRandomRelayOnErrors - если true то переотправка через случайный smtp сервер из перечня доступных разрешена.
resendViaRandomRelayAttempts - число попыток переотправить письмо через случайный smtp сервер. Для каждой попытки выбирается новый случайный smtp сервер из перечня доступных (заданных в массиве relaysOptions.relaysList).
alwaysUseBuiltInServerForDomains - массив с доменами, письма на которые будут отправляться только через встроенный smtp сервер в случае если используется смешанный режим рассылки т.е. параметр deliveryMode содержит RelaysAndBuiltInServerOnErrors или BuiltInServerAndRelaysOnErrors.
builtInServerTargetDomainsThrottleList - массив содержит настройки скоростных ограничений рассылки через встроенный smtp сервер на заданные домены получателей (например, на @gmail.com и @hotmai.com отправлять медленнее чем на остальные домены в списке рассылки).
domainName - имя целевого домена, для которого нужно установить скоростной лимит.
limitSendingThreads - если true то будет введено ограничение на число одновременных соединений (потоков отправки) на MX сервер указанного домена.
maxSendingThreads - если limitSendingThreads=true - в этом параметре передается число одновременных соединений (потоков отправки), которое нельзя превышать.
throttleOptions - объект содержит настройки ограничений скорости отправки на указанный домен:
throttleEnabled - если true то ограничение скорости включено.
msgNumber - максимальное число писем, которые могут быть отправлены за указанное время.
perMinutes - число минут за которые может быть отправлено не больше писем, чем указано в параметре msgNumber. |
{ "jsonrpc":"2.0", "result":{ "id":18, "name":"Example preset", "deliveryMode":"RelaysOnly", "commonOptions":{ "dnsResolverAttempts":2, "sendingAttempts":3, "netTimeout":60, "maxMessagesPerSmtpSession":2, "sendingMethod":"PersonalCopy", "useProxy":false, "proxyListID":1, "advancedProxyOptions":{ "maxThreadsPerProxy":0, "proxyRotationOptions":{ "enableProxyRotation":false, "rotationPoolSize":10, "rotationPoolSwitchInterval":100, "syncProxyRotationWithRelaysRoation":false, "restartSyncRotationIfAllProxiesUsed":false }, "proxyAutoExclusionOptions":{ "enableAutoExclusion":false, "proxyExclusionMode":"ByNumberOfFailedConnections", "proxyExclusionValue":50, "proxyExclusionTime":20 } }, "useMultiHomeIP":false, "muiltiHomeIpList":[
], "heloMode":"Default", "globalSpeedThrottle":{ "throttleEnabled":false, "msgNumber":10, "perSeconds":60 } }, "relaysOptions":{ "relaysList":[ { "enabled":true, "uniqID":"9TMdmnerZUeOpRSdm_lhKA", "primaryOptions":{ "serverName":"smtp.mailserver.com", "port":25, "threads":3, "bccSize":10, "authOptions":{ "enableAuthentication":true, "authType":"Auto", "login":"from@mailserver.com", "password":"mailboxpass", "useLoginAsFromEmail":true }, "sslOptions":{ "sslEnabled":true, "sslMode":"Auto" }, "throttleOptions":{ "throttleEnabled":false, "msgNumber":25, "perSeconds":120 } }, "additionalOptions":{ "socksRelayLink":"", "customHelo":"", "customFromName":"", "comment":"", "customMsgBodyFileName":"" }, "speedThrottleListForTargetDomains":[ { "domainName":"gmail.com", "throttleOptions":{ "msgNumber":100, "perMinutes":5 } } ] } ], "advancedRelaysOptions":{ "relaysResendingOptions":{ "enableResendViaRandomRelay":false, "resendViaRandomRelayAttempts":2, "enableResendViaBuiltInServer":false, "resendViaBuiltInServerAttempts":2 }, "relaysAutoExclusionOptions":{ "enableAutoExclusion":true, "excludeOnErrorsCount":5, "excludeForSeconds":300, "markRelayAsBadOnExclusionOrAuthErrors":true }, "relaysRotationOptions":{ "enableRelaysRotation":false, "rotationPoolSize":3, "rotationPoolSwitchInterval":20 }, "alwaysUseRelaysForDomains":[ "domain1.com" ] }, "relaysSpeedThrottleForTargetDomains":{ "domainsThrottleUsageMode":"ShareBetweenRelays", "domainsThrottleList":[ { "domainName":"hotmail.com", "throttleOptions":{ "msgNumber":100, "perMinutes":10 } } ] } }, "builtInServerOptions":{ "builtInServerThreads":100, "maxBccSize":10, "maxThreadsPerTargetDomain":0, "builtInServerResendingOptions":{ "enableResendViaRandomRelayOnErrors":false, "resendViaRandomRelayAttempts":2 }, "alwaysUseBuiltInServerForDomains":[ "domain2.com" ], "builtInServerTargetDomainsThrottleList":[ { "domainName":"yahoo.com", "limitSendingThreads":true, "maxSendingThreads":3, "throttleOptions":{ "throttleEnabled":true, "msgNumber":100, "perMinutes":10 } } ] } }, "id":1 } |
addAmswebLink |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"addAmswebLink", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "url":"https://www.mysite.com/folder/amsweb.php", "password":"mypass" }, "id":"1" } |
||
Результат вызова содержит ID добавленной ссылки или ошибку: |
||
{ "jsonrpc":"2.0", "result":{ "newResourceID":21 }, "id":1 } |
editAmswebLink |
Команда редактирует ссылку на скрипт учета статистики по открытым письмам и кликам amsweb.php
Описание параметров:
apiKey - ключ доступа к API
id - id ссылки, которую требуется отредактировать. Получить список имеющихся ссылок можно с помощью команды getAmswebLinks
url - прямая ссылка на скрипт amsweb.php, установленный на вашем сайте.
password - пароль доступа к скрипту (который вы задали внутри скрипта amsweb.php). |
Пример вызова:
{ "jsonrpc":"2.0", "method":"editAmswebLink", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":10, "url":"https://www.new-domain.com/folder/amsweb.php", "password":"newpass" }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
deleteAmswebLink |
Команда удаляет ссылку на скрипт учета статистики по открытым письмам и кликам amsweb.php
Описание параметров:
apiKey - ключ доступа к API
id - id ссылки, которую требуется удалить, обязательный параметр. Получить список имеющихся ссылок можно с помощью команды getAmswebLinks. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"deleteAmswebLink", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":10 }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
getAmswebLinks |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"getAmswebLinks", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875" }, "id":"1" } |
||
Результат содержит массив с имеющимися ссылками на скрипт amsweb.php:
id - id ссылки на amsweb.php
url - url ссылки.
status - текущее состояние ссылки, может содержать ошибку если статистику не удалось получить по каким-то причинам |
||
{ "jsonrpc":"2.0", "result":[ { "id":9, "url":"https:\/\/www.mysite.com\/stat\/amsweb.php", "status":"Statistics received" }, { "id":11, "url":"https:\/\/new-domain.com\/folder\/amsweb.php", "status":"Error: connection refused" } ], "id":1 } |
addDkimSignature |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"addDkimSignature", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "enabled":true, "domain":"my-domain.com", "privateKey":"-----BEGIN RSA PRIVATE KEY-----\r\nMIICWwIBAAKBgQCj3eOUrvB\/dfhv6ZkeXIZKmvG6XCRoUWKi26BZ\/YITDPFwqtxd\r\nr141oyv+i9bBqXa6iz6+RHErqTu2xqlpRqn+BQp\/bqnTCNHb+6fECKACtkHQWVeE\r\nwsZIKVtCiKDG407S8lVXZO0JJyp1wHgz6M031fYghMBM5esGPrvMi9qVSQIDAQAB\r\nAoGAeYfOCm54JT\/8AhwQmIjsfBZQIvPFeKyrZ7dVRIiUWManpfTCPKUcTNF4hm91\r\n1el2CcHNxdUCzevUQqkx6ccjuPZz9GCx5I3a5GSJXayrCrtOuRc6+c+cBjUrKMqi\r\nLceeZYewT3fukXGCm+x\/qHEUIjT\/bP4Npqe1pvw0S7JHSNECQQDPvqpTiMcSCtsp\r\nYAbFGW+ad3u7u2+k8sK4tHM4yKR86+Tq5mBbadZ\/CK+YfeF4i1N+aw7fN3y50mN6\r\nY9U37\/N9AkEAye4Pg1Q2vPm7r2i27W2qRqkxriRtgNs06aRZsQZe6F+wmaUPnIis\r\nbER8eJMp9Uga\/xOFEbrd09on1lAeb+e6vQJAQrHDnO3cez5g\/feGNODlo4GYh7y1\r\nKw+E1CealjBUHobdB0zOwopIAqCXPy2qpTiVpZBZRfBaao3Qwgoq+bpfQQJABQgS\r\niOIzTvgmDhPc4wOlh4c1vrIXrGtJ4TyAI6IWAVJJEzsCrZLWQQhf1Z1NIVh\/m7V\/\r\nzlZKqrm33mY2q\/EpPQJARUrduKkT5GdEOpwZeXC404nYGO2FaTYzs6qej+aKiv+x\r\nI\/vldM4vc2u5WjYy+cMbq88MXVBYA8eCYwX5ic3Byw==\r\n-----END RSA PRIVATE KEY-----\r\n", "selector":"mail", "useInDeliveryMode":"AnyDeliveryMode", "signatureAppearance":{ "lineBreaksInSignature":"Random", "dkimTagsMode":"Custom", "customTags":[ { "tagName":"b", "enabled":true }, { "tagName":"bh", "enabled":true }, { "tagName":"a", "enabled":true }, { "tagName":"d", "enabled":true }, { "tagName":"i", "enabled":false }, { "tagName":"s", "enabled":true }, { "tagName":"c", "enabled":true }, { "tagName":"x", "enabled":true }, { "tagName":"q", "enabled":true }, { "tagName":"t", "enabled":true }, { "tagName":"h", "enabled":true }, { "tagName":"v", "enabled":true } ] } }, "id":"1" } |
||
Результат вызова содержит ID добавленной DKIM подписи или ошибку: |
||
{ "jsonrpc":"2.0", "result":{ "newResourceID":21 }, "id":1 } |
editDkimSignature |
Команда редактирует DKIM подпись
Описание параметров:
apiKey - ключ доступа к API.
id - id подписи, которую нужно отредактировать. Обязательный параметр. Список имеющихся подписей можно получить с помощью команды getDkimSignatures
Все остальные параметры могут быть такими же как и у команды addDkimSignature, но не обязательно передавать их все если нужно изменить только какую-то конкретную настройку. Например, если вы хотите только изменить имя селектора DKIM подписи - достаточно будет передать параметр selector и больше ничего. Те объекты, которые не передавались в параметрах команды - останутся без изменений. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"editDkimSignature", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":1, "enabled":true, "domain":"new-domain.com", "privateKey":"-----BEGIN RSA PRIVATE KEY-----\r\nMIICWwIBAAKBgQCj3eOUrvB\/dfhv6ZkeXIZKmvG6XCRoUWKi26BZ\/YITDPFwqtxd\r\nr141oyv+i9bBqXa6iz6+RHErqTu2xqlpRqn+BQp\/bqnTCNHb+6fECKACtkHQWVeE\r\nwsZIKVtCiKDG407S8lVXZO0JJyp1wHgz6M031fYghMBM5esGPrvMi9qVSQIDAQAB\r\nAoGAeYfOCm54JT\/8AhwQmIjsfBZQIvPFeKyrZ7dVRIiUWManpfTCPKUcTNF4hm91\r\n1el2CcHNxdUCzevUQqkx6ccjuPZz9GCx5I3a5GSJXayrCrtOuRc6+c+cBjUrKMqi\r\nLceeZYewT3fukXGCm+x\/qHEUIjT\/bP4Npqe1pvw0S7JHSNECQQDPvqpTiMcSCtsp\r\nYAbFGW+ad3u7u2+k8sK4tHM4yKR86+Tq5mBbadZ\/CK+YfeF4i1N+aw7fN3y50mN6\r\nY9U37\/N9AkEAye4Pg1Q2vPm7r2i27W2qRqkxriRtgNs06aRZsQZe6F+wmaUPnIis\r\nbER8eJMp9Uga\/xOFEbrd09on1lAeb+e6vQJAQrHDnO3cez5g\/feGNODlo4GYh7y1\r\nKw+E1CealjBUHobdB0zOwopIAqCXPy2qpTiVpZBZRfBaao3Qwgoq+bpfQQJABQgS\r\niOIzTvgmDhPc4wOlh4c1vrIXrGtJ4TyAI6IWAVJJEzsCrZLWQQhf1Z1NIVh\/m7V\/\r\nzlZKqrm33mY2q\/EpPQJARUrduKkT5GdEOpwZeXC404nYGO2FaTYzs6qej+aKiv+x\r\nI\/vldM4vc2u5WjYy+cMbq88MXVBYA8eCYwX5ic3Byw==\r\n-----END RSA PRIVATE KEY-----\r\n", "selector":"new-selector", "useInDeliveryMode":"AnyDeliveryMode", "signatureAppearance":{ "lineBreaksInSignature":"Random", "dkimTagsMode":"Custom", "customTags":[ { "tagName":"b", "enabled":true }, { "tagName":"bh", "enabled":true }, { "tagName":"a", "enabled":true }, { "tagName":"d", "enabled":true }, { "tagName":"i", "enabled":false }, { "tagName":"s", "enabled":true }, { "tagName":"c", "enabled":true }, { "tagName":"x", "enabled":true }, { "tagName":"q", "enabled":true }, { "tagName":"t", "enabled":true }, { "tagName":"h", "enabled":true }, { "tagName":"v", "enabled":true } ] } }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
deleteDkimSignature |
Команда удаляет DKIM подпись.
Описание параметров:
apiKey - ключ доступа к API
id - id DKIM подписи, которую требуется удалить, обязательный параметр. Получить список имеющихся подписей можно с помощью команды getDkimSignatures. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"deleteDkimSignature", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":2 }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
getDkimSignatures |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"getDkimSignatures", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875" }, "id":"1" } |
||
Результат содержит массив с имеющимися DKIM подписями:
id - id DKIM подписи
enabled - если true то DKIM подпись включена.
domain - домен, для которого эта подпись.
selector - имя селектора DKIM подписи
useInDeliveryMode - режим рассылки, для которого будет использоваться данная подпись. Возможные значения:
BuiltInServerOnly - подпись будет использоваться только при рассылке в режиме встроенного Smtp сревера. RemoteRelaysOnly - подпись будет использовать только при рассылке через smtp сервера (релеи). AnyDeliveryMode - подпись будет использоваться при любых режимах рассылки. |
||
{ "jsonrpc":"2.0", "result":[ { "id":1, "enabled":true, "domain":"my-domain.com", "selector":"mail", "useInDeliveryMode":"AnyDeliveryMode" }, { "id":2, "enabled":true, "domain":"domain2.com", "selector":"newdkim", "useInDeliveryMode":"BuiltInServerOnly" } ], "id":1 } |
getDkimSignature |
Команда возвращает подробную информацию о DKIM подписи
apiKey - ключ доступа к API
id - id DKIM подписи, информацию о которой нужно получить, обязательный параметр. Получить список имеющихся подписей можно с помощью команды getDkimSignatures. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"getDkimSignature", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":1 }, "id":"1" } |
Результат содержит объект с JSON представлением настроек нужной подписи. Данный объект можно использовать как образец для команд addDkimSignature, editDkimSignature:
id - id DKIM подписи
enabled - если true - подпись включена. Значение по умолчанию true.
domain - имя домена, для которого создается подпись. Обязательный параметр.
publicKey - публичный RSA ключ DKIM подписи.
privateKey - приватный RSA ключ для DKIM подписи, из нее будет автоматически извлечен и публичный ключ. Если параметр не задан - будет автоматически сгенерирована новая пара RSA ключей.
selector - имя селектора DKIM подписи, обязательный параметр.
dnsRecord - данные для размещения публичного ключа DKIM подписи в виде TXT записи в DNS зоне вашего домена.
dnsRecord.recordName - имя TXT записи для DKIM. dnsRecord.recordValue - содержимое TXT записи.
useInDeliveryMode - параметр определяет в каком режиме рассылки будет использоваться создаваемая DKIM подпись. Возможные значения:
BuiltInServerOnly - подпись будет использоваться только при рассылке в режиме встроенного Smtp сревера. RemoteRelaysOnly - подпись будет использовать только при рассылке через smtp сервера (релеи). AnyDeliveryMode - подпись будет использоваться при любых режимах рассылки. Значение по умолчанию.
signatureAppearance - опциональный объект, в котором вы можете задать внешний вид подписи (чтобы по ее виду нельзя было определить, что она была создана в программе рассылки AMS).
signatureAppearance.lineBreaksInSignature - параметр определяет, будет ли подпись содержать переносы строк или она будет выглядеть как одна длинная строка. Возможные значения:
Enabled - переносы разрешены, значение по умолчанию. Disabled - переносы запрещены Random - для каждого письма включение/выключение переносов будет выбираться случайным образом.
signatureAppearance.dkimTagsMode - параметр определяет набор и порядок следования DKIM тэгов в подписи. Возможные значения:
Default - используется набор и порядок тегов по умлочанию Random - для каждого письма используется случайный набор и порядок тегов в DKIM подписи. Custom - используется набор и порядок DKIM тэгов заданный пользователем в массиве customTags. Некоторые тэги обязательно должны быть включены, а некоторые опциональны. Используйте с осторожностью ! Рекомендуется задать нужный набор тэгов в интерфейсе AMS, получить json представление подписи с помощью команды getDkimSignature и использовать полученный массив customTags как образец при создании ваших подписей с желаемыми настройками.
customTags - пользовательский набор DKIM тэгов для подписи. Тэги используются в том порядке, как заданы в этом массиве.
customTags.tagName - имя DKIM тэга. customTags.enabled - если true тэг включен. |
{ "jsonrpc":"2.0", "result":{ "id":1, "enabled":true, "domain":"my-domain.com", "publicKey":"-----BEGIN PUBLIC KEY-----\r\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCj3eOUrvB\/dfhv6ZkeXIZKmvG6\r\nXCRoUWKi26BZ\/YITDPFwqtxdr141oyv+i9bBqXa6iz6+RHErqTu2xqlpRqn+BQp\/\r\nbqnTCNHb+6fECKACtkHQWVeEwsZIKVtCiKDG407S8lVXZO0JJyp1wHgz6M031fYg\r\nhMBM5esGPrvMi9qVSQIDAQAB\r\n-----END PUBLIC KEY-----\r\n", "privateKey":"-----BEGIN RSA PRIVATE KEY-----\r\nMIICWwIBAAKBgQCj3eOUrvB\/dfhv6ZkeXIZKmvG6XCRoUWKi26BZ\/YITDPFwqtxd\r\nr141oyv+i9bBqXa6iz6+RHErqTu2xqlpRqn+BQp\/bqnTCNHb+6fECKACtkHQWVeE\r\nwsZIKVtCiKDG407S8lVXZO0JJyp1wHgz6M031fYghMBM5esGPrvMi9qVSQIDAQAB\r\nAoGAeYfOCm54JT\/8AhwQmIjsfBZQIvPFeKyrZ7dVRIiUWManpfTCPKUcTNF4hm91\r\n1el2CcHNxdUCzevUQqkx6ccjuPZz9GCx5I3a5GSJXayrCrtOuRc6+c+cBjUrKMqi\r\nLceeZYewT3fukXGCm+x\/qHEUIjT\/bP4Npqe1pvw0S7JHSNECQQDPvqpTiMcSCtsp\r\nYAbFGW+ad3u7u2+k8sK4tHM4yKR86+Tq5mBbadZ\/CK+YfeF4i1N+aw7fN3y50mN6\r\nY9U37\/N9AkEAye4Pg1Q2vPm7r2i27W2qRqkxriRtgNs06aRZsQZe6F+wmaUPnIis\r\nbER8eJMp9Uga\/xOFEbrd09on1lAeb+e6vQJAQrHDnO3cez5g\/feGNODlo4GYh7y1\r\nKw+E1CealjBUHobdB0zOwopIAqCXPy2qpTiVpZBZRfBaao3Qwgoq+bpfQQJABQgS\r\niOIzTvgmDhPc4wOlh4c1vrIXrGtJ4TyAI6IWAVJJEzsCrZLWQQhf1Z1NIVh\/m7V\/\r\nzlZKqrm33mY2q\/EpPQJARUrduKkT5GdEOpwZeXC404nYGO2FaTYzs6qej+aKiv+x\r\nI\/vldM4vc2u5WjYy+cMbq88MXVBYA8eCYwX5ic3Byw==\r\n-----END RSA PRIVATE KEY-----\r\n", "selector":"mail", "dnsRecord":{ "recordName":"mail._domainkey.my-domain.com", "recordValue":"v=DKIM1;t=s;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCj3eOUrvB\/dfhv6ZkeXIZKmvG6XCRoUWKi26BZ\/YITDPFwqtxdr141oyv+i9bBqXa6iz6+RHErqTu2xqlpRqn+BQp\/bqnTCNHb+6fECKACtkHQWVeEwsZIKVtCiKDG407S8lVXZO0JJyp1wHgz6M031fYghMBM5esGPrvMi9qVSQIDAQAB" }, "useInDeliveryMode":"AnyDeliveryMode", "signatureAppearance":{ "lineBreaksInSignature":"Random", "dkimTagsMode":"Custom", "customTags":[ { "tagName":"b", "requiredTag":true, "enabled":true }, { "tagName":"bh", "requiredTag":true, "enabled":true }, { "tagName":"a", "requiredTag":true, "enabled":true }, { "tagName":"d", "requiredTag":true, "enabled":true }, { "tagName":"i", "requiredTag":false, "enabled":false }, { "tagName":"s", "requiredTag":true, "enabled":true }, { "tagName":"c", "requiredTag":true, "enabled":true }, { "tagName":"x", "requiredTag":false, "enabled":true }, { "tagName":"q", "requiredTag":false, "enabled":true }, { "tagName":"t", "requiredTag":false, "enabled":true }, { "tagName":"h", "requiredTag":true, "enabled":true }, { "tagName":"v", "requiredTag":true, "enabled":true } ] } }, "id":1 } |
addPostmasterAccount |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"addPostmasterAccount", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "accountName":"My account", "refreshToken":"8cad56e3bf57f7aab9a7dc54dcf5467b4df9085a3537363331", "useProxy":false, "proxyListID":12 }, "id":"1" } |
||
Результат вызова содержит ID добавленного аккаунта postmaster.mail.ru подписи или ошибку: |
||
{ "jsonrpc":"2.0", "result":{ "newResourceID":21 }, "id":1 } |
editPostmasterAccount |
Команда редактирует аккаунт postmater.mail.ru
Описание параметров:
apiKey - ключ доступа к API
id - id аккаунта, который нужно отредактировать. Получить список имеющихся аккаунтов можно с помощью команды getPostmasterAccounts.
Все остальные параметры могут быть такими же как и у команды addPostmasterAccount, но не обязательно передавать их все если нужно изменить только какую-то конкретную настройку. Например, если вы хотите только изменить имя аккаунта - достаточно будет передать параметр accountName и больше ничего. Те объекты, которые не передавались в параметрах команды - останутся без изменений. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"editPostmasterAccount", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":7, "accountName":"New account name", "refreshToken":"8cad56e3bf57f7aab9a7dc54dcf5467b4df9085a3537363331", "useProxy":false, "proxyListID":12 }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
deletePostmasterAccount |
Команда удаляет аккаунт postmaster.mail.ru
Описание параметров:
apiKey - ключ доступа к API
id - id аккаунта, который нужно удалить. Получить список имеющихся аккаунтов можно с помощью команды getPostmasterAccounts. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"deletePostmasterAccount", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":7 }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
getPostmasterAccounts |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"getPostmasterAccounts", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875" }, "id":"1" } |
||
Результат содержит массив с имеющимися аккаунтами postmaster.mail.ru:
id - id аккаунта postmaster.mail.ru
accountName - имя аккаунта
status - состояние обмена данными с сервисом postmaster.mail.ru или ошибка
useProxy - если true то для приема данных используется прокси.
proxyListID - id прокси листа, чьи прокси используются для приема данных.
lastUpdateTime - дата/время последнего сеанса связи с сервисом postmaster.mail.ru
domains - массив с доменами, которые привязаны к этому аккаунту в сервисе postmaster.mail.ru |
||
{ "jsonrpc":"2.0", "result":[ { "id":4, "accountName":"My account", "status":"Statistics received 13:13:43, 08.03.2024", "useProxy":false, "proxyListID":921, "lastUpdateTime":"2024-03-08T13:13:43.472", "domains":[ "domain1.ru", "domain2.ru", "domain3.ru" ] }, { "id":6, "accountName":"new account", "status":"Statistics received 13:13:27, 08.03.2024", "useProxy":false, "proxyListID":1, "lastUpdateTime":"2024-03-08T13:13:27.512", "domains":[ "domain4.ru", "domain5.ru" ] } ], "id":1 } |
addProxyList |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"addProxyList", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "proxyListName":"My proxy list", "connectMode":"Fast" }, "id":"1" } |
||
Результат вызова содержит ID добавленного списка прокси или ошибку: |
||
{ "jsonrpc":"2.0", "result":{ "newResourceID":21 }, "id":1 } |
editProxyList |
Команда редактирует параметры списка прокси.
Описание параметров:
apiKey - ключ доступа к API
id - id списка прокси, который нужно отредактировать. Получить список имеющихся списков прокси можно с помощью команды getProxyLists
Все остальные параметры могут быть такими же как и у команды addProxyList, но не обязательно передавать их все если нужно изменить только какую-то конкретную настройку. Например, если вы хотите только изменить имя списка прокси - достаточно будет передать параметр proxyListName и больше ничего. Те объекты, которые не передавались в параметрах команды - останутся без изменений. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"editProxyList", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":3, "proxyListName":"New list name", "connectMode":"Normal" }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
deleteProxyList |
Команда удаляет список прокси.
Описание параметров:
apiKey - ключ доступа к API
id - id списка прокси, который нужно удалить. Получить список имеющихся списков прокси можно с помощью команды getProxyLists. Нельзя удалить список прокси, который используется в запущенных рассылках ! |
Пример вызова:
{ "jsonrpc":"2.0", "method":"deleteProxyList", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":3 }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
updateProxyList |
Команда задает содержимое списка прокси (т.е. позволяет загрузить прокси в список).
Описание параметров:
apiKey - ключ доступа к API
id - id списка прокси, содержимое которого нужно задать, обязательный параметр.
allowDuplicates - если true - разрешает добавление дубликатов прокси в целевой список. Значение по умолчанию false.
updateMode - режим добавления прокси в список. Возможные значения:
Append - новые прокси будут добавлены в конец целевого списка. Значение по умолчанию. Overwrite - перед загрузкой новых прокси целевой список будет очищен (из него будут удалены все прокси, которые там есть на момент вызова команды).
proxies - массив с прокси, которые нужно загрузить в список. Обязательный параметр.
enabled - если true - прокси включен и будет использован в рассылках. По умолчанию true.
ip - ip адрес прокси. Должен быть в виде IPv4 или IPv6. Имена хостов не поддерживаются. Обязательный параметр.
outIp - если выходной IP прокси отличается от входного и при этом вы его знаете - вы можете передать выходной IP в этом параметре. Если прокси содержит выходной IP - он будет использован во время проверки прокси по RBL блок-листам.
port - номер порта прокси. Обязательный параметр.
type - тип прокси, обязательный параметр. Возможные значения:
Socks5 - прокси типа Socks5 Http - это http прокси (туннель) Ssh - это ssh туннель. Для работы прокси в режиме ssh туннеля - порт прокси должен быть 22 или 222 или 2222 или 22222. Auto - тип прокси будет определен автоматически во время проверки.
host - имя хоста (содержимое PTR записи), привязанное к IP адресу прокси. Если задан - будет использоваться в качестве аргумента Smtp команды HELO во время рассылки (если в профиле отправки выбрана опция HELO "Использовать имена хостов прокси")
comment - любая пользовательская строка, которую можно подставить в любое место письма с помощью макроса [%%PProxyComment%%]
authOptions - если прокси требует авторизацию по логину-паролю вы можете передать их в этом объекте:
enableAuthentication - значение должно быть true если прокси требует авторизацию. login - логин прокси. password - пароль прокси.
throttleOptions - если требуется ограничить скорость отправки через этот прокси - вы можете передать в этом объекте настройки скоростного лимита:
throttleEnabled - если true то ограничение скорости включено. msgNumber - число писем, которые можно отправить за заданный период времени. perSeconds - число секунд, в течении которых должно быть отправлено не больше писем, чем указано в параметре msgNumber. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"updateProxyList", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":1, "updateMode":"Append", "allowDuplicates":false, "proxies":[ { "enabled":true, "ip":"125.46.24.62", "outIp":"", "port":1080, "type":"Socks5", "host":"some.host.com", "comment":"my test comment", "authOptions":{ "enableAuthentication":false, "login":"", "password":"" }, "throttleOptions":{ "throttleEnabled":false, "msgNumber":1, "perSeconds":5 } }, { "enabled":true, "ip":"123.16.44.12", "outIp":"66.22.14.41", "port":22345, "type":"Socks5", "host":"", "comment":"", "authOptions":{ "enableAuthentication":true, "login":"user", "password":"pass" }, "throttleOptions":{ "throttleEnabled":true, "msgNumber":100, "perSeconds":5000 } } ] }, "id":1 } |
Результат содержит число добавленных прокси и, если параметр allowDuplicates=false, число обнаруженных дубликатов: |
{ "jsonrpc":"2.0", "result":{ "recordsAdded":1, "duplicatesFound":1 }, "id":1 } |
getProxyLists |
Команда возвращает список имеющихся списков прокси.
Описание параметров:
apiKey - ключ доступа к API |
Пример вызова:
{ "jsonrpc":"2.0", "method":"getProxyLists", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875" }, "id":"1" } |
Результат вызова содержит массив с имеющимися списками прокси:
id - id списка прокси. name - имя списка прокси. |
{ "jsonrpc":"2.0", "result":[ { "id":1, "name":"Default proxy list" }, { "id":2, "name":"My proxy list" } ], "id":1 } |
getProxyList |
Команда возвращает подробную информацию о списке прокси, а так же его содержимое.
Описание параметров:
apiKey - ключ доступа к API
id - id списка прокси, информацию и содержимое которого нужно получить. |
Пример вызова:
{ "jsonrpc":"2.0", "method":"getProxyList", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "id":1 }, "id":"1" } |
Результат вызова содержит информацию о списке прокси и его содержимое:
id - id списка прокси.
proxyListName - имя списка прокси.
connectionMode - режим соединения, который будет использоваться для прокси в этом списки. Возможные значения:
Normal - обычный режим соединения (прокси передается имя целевого хоста и преобразования имя хоста->IP выполняет прокси). Fast - быстрый режим соединения (преобразование имя хоста->IP выполняет AMS и прокси передается уже IP целевого хоста). Значение по умолчанию.
proxies - массив с прокси, который содержит список прокси.
enabled - если true - прокси включен.
ip - ip адрес прокси.
outIp - выходной IP прокси, если известен.
port - номер порта прокси.
type - тип прокси, возможные значения:
Socks5 - прокси типа Socks5 Http - это http прокси (туннель) Ssh - это ssh туннель. Auto - тип прокси будет определен автоматически во время проверки.
host - имя хоста (содержимое PTR записи), привязанное к IP адресу прокси.
comment - любая пользовательская строка, которую можно подставить в любое место письма с помощью макроса [%%PProxyComment%%]
authOptions - объект с настройками авторизации прокси:
enableAuthentication - если true то авторизация включена. login - логин прокси. password - пароль прокси.
throttleOptions - объект с настройками ограничения скорости отправки через прокси.
throttleEnabled - если true то ограничение скорости включено. msgNumber - число писем, которые можно отправить за заданный период времени. perSeconds - число секунд, в течении которых должно быть отправлено не больше писем, чем указано в параметре msgNumber. |
{ "jsonrpc":"2.0", "result":{ "id":"1", "proxyListName":"Default proxy list", "connectMode":"Fast", "proxies":[ { "enabled":true, "ip":"123.16.44.12", "outIp":"66.22.14.41", "port":22345, "type":"Socks5", "host":"", "comment":"", "checkResult":"Unknown", "rblCheckResult":"Unchecked", "authOptions":{ "enableAuthentication":true, "login":"user", "password":"pass" }, "throttleOptions":{ "throttleEnabled":true, "msgNumber":100, "perSeconds":5000 } }, { "enabled":true, "ip":"125.46.24.62", "outIp":"", "port":1080, "type":"Socks5", "host":"some.host.com", "comment":"my test comment", "checkResult":"Unknown", "rblCheckResult":"Unchecked", "authOptions":{ "enableAuthentication":false, "login":"", "password":"" }, "throttleOptions":{ "throttleEnabled":false, "msgNumber":1, "perSeconds":5 } } ] }, "id":1 } |
getRelaysSendingStates |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"getRelaysSendingStates", "params":{ "apiKey":"B62ABC84-BA11-4DA9-BD1A-9F975B55DC8D", "mailingID":186 }, "id":"1" } |
||
Результат содержит массив с Smtp серверами и их состояниями, используемыми в заданной рассылке:
relayInfo - объект с информацией о релее.
id - текущий индекс релея в рассылки. При следующем запуске рассылки у релея может быть другой id если список релеев в профиле отправки редактировался. Т.е. этот id является валидным только пока работает рассылка.
uniqID - уникальный, постоянный ID релея, который не меняется при редактировании профиля отправки.
serverName - имя smtp сервера.
serverPort - порт smtp сервера.
sslOptions - объект с настройками SSL/TLS соединения у этого smtp сервера.
sslEnabled - если true то поддержка SSL/TLS включена.
sslMode - режим ssl/tls соединения, возможные значения:
Auto - режим выбирается автоматически в зависимости от номера порта и ответа smtp команды EHLO.
SslConnection - режим ssl соединение, обычно когда номер порта 465.
StartTls - защищенное соединение устанавливаться с помощью команды Smtp STARTTLS.
login - логин smtp сервера.
socksRelayLink - если включена жесткая связка Smtp сервера с некоторым прокси - здесь будет IP этого прокси.
customFromName - кастомное имя отправителя (для поля From:), связанное с этим smtp сервером.
comment - пользовательский комментарий, заданный для этого smtp сервера.
customBodyFile - если для этого smtp сервера используется кастомное тело письма (с помощью макроса [%%OMessageBodyByRelay%%] - в этом поле будет имя файла с кастомным телом письма.
speedThrottle - в этом объекте хранятся настройки ограничения скорости рассылки для этого smtp сервера.
throttleEnabled - если true то ограничение скорости включено.
msgNumber - число писем, которое может быть отправлено за заданный период времени.
perSeconds - интервал в секундах, за который может быть отправлено не больше писем чем указано в параметре msgNumber.
sendingState - объект, в котором хранится статистика отправки и прогресс для этого smtp сервера.
sent - число писем, который отправил данный smtp сервер с последнего перезапуска рассылки с начала (или с последнего запуска рассылки если в окне Настройки->Доп. настройки не включено сохранение состояний релеев при остановке рассылки).
errors - число ошибок отправки у данного smtp сервера с последнего перезапуска рассылки с начала (или с последнего запуска рассылки если в окне Настройки->Доп. настройки не включено сохранение состояний релеев при остановке рассылки).
errorsInRow - число ошибок отправки подряд. При успешной отправки письма это число сбрасывается в 0. Таким образом, если в этом параметре больше число - данный smtp сервер уже давно не может ничего отправить.
lastDeliveryErrors - последние ошибки отправки у этого smtp сервера.
errorTime - дата/время возникновения ошибки доставки.
error - текст ошибки.
toDomain - на какой домен получателя выполнялась отправка когда произошла ошибка.
fromDomain - с какого домена (имеется ввиду домен обратного (From:) адреса) была отправка когда произошла ошибка.
enabled - если true то smtp сервер включен и отправляет письма.
excluded - если true то smtp сервер временно исключен из рассылки из-за множества ошибок доставки (настройка автоматического исключения задается в Профиле отправки или задается вручную с помощью команды changeRelaySendingOption).
inThrottlePause - если true то smtp сервер находится в состоянии паузы из-за включенного ограничения скорости отправки.
throttleSecondsleft - сколько еще секунд smtp сервер будет находится в состоянии паузы из-за включенного ограничения скорости отправки.
rotationState - объект содержит информацию о состоянии ротации этого smtp сервера.
rotationEnabled - если true то ротация smtp серверов включена.
inActiveRotationPool - если true то smtp сервер находится в активном пуле ротации и отправляет письма.
waitingForRotation - если true то smtp сервер ожидает когда до него дойдет очередь ротации. |
||
{ "jsonrpc":"2.0", "result":[ { "relayInfo":{ "id":0, "uniqID":"NjqNWkP2BkarFD1R4OvFzg", "serverName":"smtp.my-domain.ru", "serverPort":587, "sslOptions":{ "sslEnabled":true, "sslMode":"Auto" }, "login":"pmtauser:::from@my-domain.ru", "socksRelayLink":"", "customFromName":"", "customHelo":"", "comment":"", "customBodyFile":"", "speedThrottle":{ "throttleEnabled":true, "msgNumber":11, "perSeconds":2 } }, "sendingState":{ "sent":21190, "errors":7, "errorsInRow":0, "lastDeliveryErrors":[ { "errorTime":"2024-03-08T17:09:49.191", "error":"500 mail.mydomain.ru says invalid EHLO argument", "toDomain":"gmail.com", "fromDomain":"mydomain.ru" }, { "errorTime":"2024-03-08T17:09:49.191", "error":"550 to many recipients", "toDomain":"gmail.com", "fromDomain":"mydomain.ru" } ], "enabled":true, "excluded":false, "excludeSecondsLeft":0, "inThrottlePause":0, "throttlePauseSecondsLeft":0, "rotationState":{ "rotationEnabled":false, "inActiveRotationPool":false, "waitingForRotation":false } } }, { "relayInfo":{ "id":1, "uniqID":"1uzWQq4S4EKhWHZm4xszxA", "serverName":"220.129.17.61", "serverPort":587, "sslOptions":{ "sslEnabled":true, "sslMode":"Auto" }, "login":"from@second-domain.ru", "socksRelayLink":"", "customFromName":"My Company.Com", "customHelo":"second-domain.ru", "comment":"", "customBodyFile":"", "speedThrottle":{ "throttleEnabled":true, "msgNumber":11, "perSeconds":2 } }, "sendingState":{ "sent":21285, "errors":0, "errorsInRow":0, "lastDeliveryErrors":[
], "enabled":true, "excluded":false, "excludeSecondsLeft":0, "inThrottlePause":0, "throttlePauseSecondsLeft":0, "rotationState":{ "rotationEnabled":false, "inActiveRotationPool":false, "waitingForRotation":false } } } ], "id":1 } |
changeRelaySendingOption |
Команда позволяет изменить параметры заданного smtp сервера у запущенной рассылки.
Описание параметров:
apiKey - ключ доступа к API
mailingID - id рассылки, у которой нужно изменить параметры у некоторого smtp сервера. Обязательный параметр. Получить список рассылок можно с помощью команды getMailings. Изменить параметры smtp сервера можно только у работающих рассылок, у которых state=working
relayID - id (индекс) smtp сервера, параметры которого нужно изменить. Обязательный параметр. Получить список smtp серверов у активной рассылки можно с помощью команды getRelaysSendingStates
optionName - имя параметра smtp сервера, который нужно изменить. Обязательный параметр. Возможные значения:
toggleEnabled - включить/включить smtp сервер.
toggleExcluded - исключить smtp сервер из рассылки на заданное время.
toggleSpeedThrottle - изменить скоростной лимит для smtp сервера.
optionParams - объект, в котором передаются настройки опции, заданные в параметре optionName:
Если optionName=toggleEnabled: relayEnabled - если true включить smtp сервер, если false то выключить.
Если optionName=toggleExcluded: relayExcluded - если true - исключить smtp сервер из рассылки, если false - вернуть ранее исключенный smtp сервер в рассылку. excludeDurationSeconds - число секунд, на которые smtp сервер должен быть исключен из рассылки.
Если optionName=toggleSpeedThrottle: throttleEnabled - если true то ограничение скорости для smtp сервера будет включено, если false то выключено. msgNumber - число писем, которое может быть отправлено за заданный период времени. perSeconds - интервал в секундах, за который smtp сервер может отправить не больше писем чем указано в параметре msgNumber. |
Примеры вызова:
Для отключения smtp сервера:
{ "jsonrpc":"2.0", "method":"changeRelaySendingOption", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "mailingID":134, "relayID":1, "optionName":"toggleEnabled", "optionParams":{ "relayEnabled":false } }, "id":"1" }
Для исключения smtp сервера из рассылки на заданное время:
{ "jsonrpc":"2.0", "method":"changeRelaySendingOption", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "mailingID":134, "relayID":0, "optionName":"toggleExcluded", "optionParams":{ "relayExcluded":true, "excludeDurationSeconds":900 } }, "id":"1" }
Для изменения скоростного лимита у smtp сервера:
{ "jsonrpc":"2.0", "method":"changeRelaySendingOption", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "mailingID":134, "relayID":0, "optionName":"toggleSpeedThrottle", "optionParams":{ "throttleEnabled":true, "msgNumber":1, "perSeconds":600 } }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
getProxiesSendingStates |
||
|
||
Пример вызова:
{ "jsonrpc":"2.0", "method":"getProxiesSendingStates", "params":{ "apiKey":"B62ABC84-BA11-4DA9-BD1A-9F975B55DC8D", "mailingID":186 }, "id":"1" } |
||
Результат содержит массив с прокси и их состояниями, используемыми в заданной рассылке:
proxyInfo - объект с информацией о прокси:
id - id прокси.
ip - IP адрес прокси.
outIP - выходной IP адрес прокси (если известен).
port - номер порта прокси.
login - логин прокси если требуется авторизация.
hostName - имя хоста, которое привязано к IP адресу прокси и было получено через DNS PTR запрос во время проверки списка прокси.
comment - пользовательский комментарий, заданный для этого прокси.
speedThrottle - в этом объекте хранятся настройки ограничения скорости рассылки для этого прокси.
throttleEnabled - если true то ограничение скорости включено.
msgNumber - число писем, которое может быть отправлено за заданный период времени.
perSeconds - интервал в секундах, за который может быть отправлено не больше писем чем указано в параметре msgNumber.
sendingState - объект, в котором хранится статистика отправки и прогресс для этого прокси.
enabled - если true - прокси включен и через него отправляются письма.
connectAttempts - число попыток установить соединение через этот прокси с целевыми smtp серверами.
errorsTotal - общее число ошибок установления соединения через этот прокси.
errorsInRow - число ошибок соединения подряд. При успешном соединение это число сбрасывается в 0. Таким образом, если в этом параметре больше число - через этот прокси уже давно не удается соединиться с целевыми smtp серверами.
totalErrors - общее число ошибок отправки через этот прокси (т.е. тут сумма ошибок соединения и других ошибок, из-за которых не удалось отправить письмо, например из-за блокировки IP адреса прокси спам фильтрами и т.д.).
sent - число писем, отправленных через этот прокси.
notSentInRow - число не отправленных писем подряд. При успешной отправки это число сбрасывается в 0. Таким образом, если в этом параметре большое число - через этот прокси уже давно не удается отправить письма.
lastDeliveryErrors - массив, содержащий последние ошибки отправки через этот прокси:
errorTime - дата/время возникновения ошибки.
error - текст ошибки.
toDomain - на какой домен получателя выполнялась отправка когда произошла ошибка.
fromDomain - с какого домена (имеется ввиду домен обратного (From:) адреса) была отправка когда произошла ошибка.
targetHost - c каким целевым smtp сервером устанавливалось соединение через этот прокси когда произошла ошибка.
effeciencyPercent - эффективность прокси (отношение успешных соединений к ошибкам соединения).
currentSendingThreads - сколько потоков отправки (сколько параллельных соединений) сейчас работает через данный прокси.
assicoatedRelayID - ID (индекс) связанного с прокси Smtp сервера если в настройках Smtp используется связка Socks<->Relay или в настройках ротации прокси включена синхронизация ротации прокси с Smtp серверами.
excluded - если true то прокси был автоматически исключен из рассылки на некоторое время из-за множества ошибок соединения или отправки писем.
excludeSecondsLeft - сколько еще секунд прокси будет исключен из рассылки.
inThrottlePause - если true то прокси находится в состоянии паузы из-за включенного ограничения скорости отправки.
throttlePauseSecondsLeft - сколько еще секунд прокси будет находится в состоянии паузы из-за включенного ограничения скорости отправки.
rotationState - объект содержит состояние ротации прокси:
rotationEnabled - если true то ротация прокси включена.
inActiveRotationPool - если true то данный прокси находится в активном пуле ротации и отправляет письма.
waitingForRotation - если true то данный прокси ожидает когда до него дойдет очередь ротации. |
||
{ "jsonrpc":"2.0", "result":[ { "proxyInfo":{ "id":676, "ip":"188.160.22.91", "outIP":"", "port":8250, "type":"Socks5", "login":"user", "hostName":"vs3605.ip-91-22-160.eu", "comment":"", "speedThrottle":{ "throttleEnabled":true, "msgNumber":1000, "perSeconds":300 } }, "sendingState":{ "enabled":true, "connectAttempts":1269, "connectErrorsTotal":0, "connectErrorsInRow":0, "totalErrors":0, "sent":1269, "notSentInRow":0, "lastDeliveryErrors":[
], "effeciencyPercent":100, "currentSendingThreads":11, "associatedRelayID":-1, "excluded":false, "excludeSecondsLeft":0, "inThrottlePause":0, "throttlePauseSecondsLeft":0, "rotationState":{ "rotationEnabled":false, "inActiveRotationPool":false, "waitingForRotation":false } } }, { "proxyInfo":{ "id":677, "ip":"118.125.96.97", "outIP":"", "port":57416, "type":"Socks5", "login":"", "hostName":"vs3605.ip-97-96-125.eu", "comment":"", "speedThrottle":{ "throttleEnabled":false, "msgNumber":20, "perSeconds":300 } }, "sendingState":{ "enabled":true, "connectAttempts":15, "connectErrorsTotal":15, "connectErrorsInRow":15, "totalErrors":15, "sent":0, "notSentInRow":1, "lastDeliveryErrors":[ { "errorTime":"2024-03-10T11:22:16.758", "error":"500 Connect error - Winsock - Connection timed out (#10060)", "toDomain":"gmail.com", "fromDomain":"mydomain.ru", "targetHost":"mx.google.com" }, { "errorTime":"2024-03-10T11:22:16.758", "error":"500 Connect error - Winsock - Connection timed out (#10060)", "toDomain":"gmail.com", "fromDomain":"mydomain.ru", "targetHost":"mx.google.com" } ], "effeciencyPercent":0, "currentSendingThreads":0, "associatedRelayID":-1, "excluded":true, "excludeSecondsLeft":928, "inThrottlePause":0, "throttlePauseSecondsLeft":0, "rotationState":{ "rotationEnabled":false, "inActiveRotationPool":false, "waitingForRotation":false } } } ], "id":1 } |
changeProxySendingOption |
Команда позволяет изменить параметры заданного прокси у запущенной рассылки.
Описание параметров:
apiKey - ключ доступа к API
mailingID - id рассылки, у которой нужно изменить параметры у некоторого прокси. Обязательный параметр. Получить список рассылок можно с помощью команды getMailings. Изменить параметры прокси можно только у работающих рассылок, у которых state=working
proxyID - id прокси, параметры которого нужно изменить. Обязательный параметр. Получить список прокси у активной рассылки можно с помощью команды getProxiesSendingStates
optionName - имя параметра прокси, который нужно изменить. Обязательный параметр. Возможные значения:
toggleEnabled - включить/включить прокси.
toggleExcluded - исключить прокси из рассылки на заданное время.
toggleSpeedThrottle - изменить скоростной лимит для прокси.
optionParams - объект, в котором передаются настройки опции, заданные в параметре optionName:
Если optionName=toggleEnabled: relayEnabled - если true включить прокси, если false то выключить.
Если optionName=toggleExcluded: relayExcluded - если true - исключить прокси из рассылки, если false - вернуть ранее исключенный прокси в рассылку. excludeDurationSeconds - число секунд, на которые прокси должен быть исключен из рассылки.
Если optionName=toggleSpeedThrottle: throttleEnabled - если true то ограничение скорости для прокси будет включено, если false то выключено. msgNumber - число писем, которое может быть отправлено за заданный период времени. perSeconds - интервал в секундах, за который прокси может отправить не больше писем чем указано в параметре msgNumber. |
Пример вызова:
Для отключения прокси:
{ "jsonrpc":"2.0", "method":"changeProxySendingOption", "params":{ "apiKey":"B62ABC84-BA11-4DA9-BD1A-9F975B55DC8D", "mailingID":186, "proxyID":676, "optionName":"toggleEnabled", "optionParams":{ "proxyEnabled":false } }, "id":"1" }
Для исключения прокси из рассылки на заданное время:
{ "jsonrpc":"2.0", "method":"changeProxySendingOption", "params":{ "apiKey":"B62ABC84-BA11-4DA9-BD1A-9F975B55DC8D", "mailingID":186, "proxyID":676, "optionName":"toggleExcluded", "optionParams":{ "proxyExcluded":true, "excludeDurationSeconds":900 } }, "id":"1" }
Для изменения скоростного лимита у прокси:
{ "jsonrpc":"2.0", "method":"changeProxySendingOption", "params":{ "apiKey":"B62ABC84-BA11-4DA9-BD1A-9F975B55DC8D", "mailingID":186, "proxyID":676, "optionName":"toggleSpeedThrottle", "optionParams":{ "throttleEnabled":true, "msgNumber":1, "perSeconds":600 } }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
postSendingJob |
Команда добавляет задание на отправку в очередь отправки транзакционной рассылки.
Транзакционная рассылка - это особый тип рассылки, для которой нельзя выбрать список получателей и которая отправляет письма исключительно на перечни контактов, переданные вместе с командой API postSendingJob из вашего ПО. Транзакционные рассылки запускаются автоматически при старте AMS и ожидают команд на отправку от сервера API. У транзакционной рассылки нет прогресса работы т.к. заранее не известно сколько получателей придет вместе с командами postSendingJob. По умолчанию отправляется письмо, выбранное для транзакционной рассылки на главном окне AMS. Однако, если вместе с командой передается параметр customMessage - содержимое письма, переданное в этом параметре переопределяет содержимое письма, выбранного для рассылки на главном окне AMS.
Описание параметров:
apiKey - ключ доступа к API
jobID - опциональный параметр для вашего идентификатора задания. Может быть удобным если ID изначально формируется на стороне вашего ПО и хранится где-то в вашей БД чтобы в последствии можно было получить результат выполнения задания с помощью команды getSendingJobID. Максимальная длинна идентификатора 38 символов. Если параметр отсутствует - уникальный идентификатор (GUID) будет сформирован автоматически и возвращен вам в результате вызова команды postSendingJob. Если идентификатор задания формируется на вашей стороне - желательно чтобы он был уникальным, в противном случае вы не сможете получить результат выполнения задания - функция getSendingJobResult вернет результат для первого задания с совпадающим jobID.
mailingID - ID транзакционной рассылки, в чью очередь отправки будет добавлено данное задание. Обязательный параметр. Список ID имеющихся рассылок можно получить с помощью команды getTransactionalMailings или 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 - тема письма. Должна в виде строки в кодировке UTF-8, дополнительно закодированной в base64.
htmlPart - содержимое Html части письма. Это должен быть Html код в кодировке UTF-8 (желательно чтобы html код содержал META тэг с указанием кодировки). Html код должен передаваться в виде строки закодированной в base64.
textPart - текстовая часть письма. Должна быть в кодировке UTF-8 и передаваться в виде строки, закодированной в base64. Значение параметра должно быть задано если messageType=Text или textPartMode=CustomTextPart
messageType - тип письма. Возможны два варианта: Html или Text. Если messageType=Html - параметр htmlPart не должен быть пустым. Если messageType=Text - параметр textPart не должен быть пустым. Данный параметр имеет ту же логику, что и эта настройка в редакторе писем:
textPartMode - режим использования текстовой части Html писем. Возможные значения:
ExtractFromHtml - автоматически сформировать текстовую часть путем извлечения текста из html части CustomTextPart - задать свою текстовую часть, текст которой будет отличаться от html части. NoTextPart - отключить текстовую часть, в этом случае типа письма будет text/html вместо multipart/alternative.
Данный параметр повторяет логику работы этой настройки в редакторе писем:
attachments - массив, в котором передаются вложения.
fileName - имя приложенного файла. fileContent - содержимое приложенного файла. Должно быть закодировано в base64.
htmlAttachments - если письмо содержит встроенные картинки - они передаются в этом массиве.
fileName - имя файла картинки. Например, если html код вашего письма содержит <img src="NetworkIcon.png"> и при этом массив htmlAttachments.fileName содержит имя файла NetworkIcon.png - то при сборке письма IMG тэг поменяется на <img src="cid:b3f106b5009ed27a741cb6030@domain.com"> и картинка будет встроено в письмо как вложение. fileContent - содержимое файла картинки. Должно быть закодировано в base64
customHeaderLines - опциональный массив строк, который необходимо добавить в конец стандартного заголовка письма. Строки добавляются в заголовок "как есть", без какого либо кодирования. Если параметр отсутствует - письмо отправляется со стандартным заголовком. Данный параметр является аналогом этой настройки Редактора писем:
|
Пример вызова:
{ "jsonrpc":"2.0", "method":"postSendingJob", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "jobID":"MyJob_ID_43455353", "mailingID":78, "contacts":[ { "ID":"1", "Email":"billgates@microsoft.com", "FullName":"Bill Gates", "City":"Redmont" }, { "ID":"2", "Email":"jeffbezos@amazon.com", "FullName":"Jeff Bezos", "City":"New York" } ], "customMessage":{ "subject":"VGhpcyBpcyBhIHRlc3Qgc3ViamVjdA==", "htmlPart":"PGh0bWw+PGhlYWQ+DQo8bWV0YSBjb250ZW50PSJ0ZXh0L2h0bWw7IGNoYXJzZXQ9LVtDSEFSU0VUXS0iIGh0dHAtZXF1aXY9Q29udGVudC1UeXBlPg0KPG1ldGEgbmFtZT1HRU5FUkFUT1IgY29udGVudD0iLVtPVVRMT09LX1ZFUl0tIj48L2hlYWQ+DQo8Ym9keSBib3R0b21NYXJnaW49NSBiZ0NvbG9yPSIjZmZmZmZmIiBsZWZ0TWFyZ2luPTUgdG9wTWFyZ2luPTUgcmlnaHRNYXJnaW49NT48Zm9udCBjb2xvcj0iIzAwMDAwMCIgc2l6ZT0yIGZhY2U9QXJpYWw+DQo8ZGl2PlRoaXMgaXMgYSBtZXNzYWdlIGJvZHkgd2l0aCBpbWFnZTwvZGl2Pg0KPGRpdj48aW1nIGJvcmRlcj0wIGhzcGFjZT0wIGFsdD0iIiBzcmM9Ik5ldHdvcmtJY29uLnBuZyIgd2lkdGg9MTYgaGVpZ2h0PTE2PjwvZGl2PjwvZm9udD48L2JvZHk+PC9odG1sPg0K", "textPart":"77u\/VGhpcyBpcyBhIG1lc3NhZ2UgYm9keSB3aXRoIGltYWdl", "messageType":"Html", "textPartMode":"ExtractFromHtml", "attachments":[ { "fileName":"ExampleAttachment.txt", "fileContent":"Q29udGVudCBvZiBhdHRhY2hlZCB0ZXh0IGZpbGU=" } ], "htmlAttachments":[ { "fileName":"NetworkIcon.png", "fileContent":"iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8\/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAg1JREFUeNqkU01rE1EUPS+Thnx0nBnTIlMXLgRFAkHp2q1uKqiUFMWVLgxUFPwPWetCF91kpe3OjwpVdwF3GiEE1JWtBktbJzNvzHwk0Xx43ziOSa246IXDu2\/eu+edc+c9NhwOsZ+IFwqF0fk5gv6fmi3Cs4hgdKXdbuvlcnnJcRx0Oh00mx5ct4dMZhLaQQ1T2SyKxYVFSZKwJ4GIXq8Hy7Jg2zZMy4NDBJqmIp5gUJTMX3KkXC43VlytVmcYY8cMw8DnTx\/RNL7gm70Dm2\/j+dqTl5zzh7FYbPNfCmZLpdJcZMFyYDttpDKpQMXcxYWzN4vXVmnf64hgMBhE1SIfs2A74J4HWZURSwwgK8lgDyn8Y0HX9eA0Ad\/3Wa1WO0xN+mVhYx3W1214nMO1ONaerr5oNBor3W5383cNy+fzoz24ValU7kYWeAumayORjkPVFGTpT8yfOX+bFNyJLNTr9SBJJpPUZUUes9BqwfA5MmoSTFg4kIJpmrJYEweIYCMNPEIk83QzD\/X7\/WCN8pnApyRtUeeHofcdui+PaFzfTaASUtG3XAJ49\/1GmN+jfOzOEfhugvFYnl7Chx+zQX5i4i0uG9f3fAuEKcJRwknCKcJxgoxlFxfKlwKCx1dXxFAlCG8bYf6G8F4omAilT4ZIC9tYTF\/BNDsdHGMMX+G+\/2BEvhPCZ\/t9zj8FGAAyaftHYMhilQAAAABJRU5ErkJggg==" } ] }, "customHeaderLines":[ "Precedense: Bulk", "X-Mailer: [%%ORandText,XMailers%%]" ] }, "id":"1" } |
Результат вызова содержит идентификатор помещенного в очередь задания или ошибку. Обратите внимание, что если параметр jobID был не пуст - функция вернет значение, переданное вами в параметре jobID. Если же параметр jobID был не задан или пуст - результат будет содержать уникальный идентификатор (GUID), сформированный программой. |
{ "jsonrpc":"2.0", "result":"MyJob_ID_43455353", "id":1 } |
getSendingJobResult |
Команда возвращает результат выполнения задания на отправку, которое было помещено в очередь транзакционной рассылки с помощью команды postSendingJob.
Описание параметров:
apiKey - ключ доступа к API
jobID - id задания, результат выполнения которого вы хотите получить. Этот id вы получили в результате отправки задания с помощью команды postSendingJob. См. описание параметра jobID и результата выполнения команды postSendingJob.
mailingID - ID транзакционной рассылки, в чью очередь было ранее отправлено задание. Обязательный параметр. Список ID имеющихся рассылок можно получить с помощью команды getTransactionalMailings или getMailings. У транзакционных рассылок параметр type = transactional |
Пример вызова:
{ "jsonrpc":"2.0", "method":"getSendingJobResult", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875", "jobID":"MyJob_ID_43455353", "mailingID":133 }, "id":"1" } |
Результат вызова содержит массив с результатами отправки для каждого получателя из массива contacts задания, полученного c командой postSendingJob:
ID - id контакта, который был передан в массиве contacts исходного задания.
Email - email адрес, который был передан в массиве contacts исходного задания.
sendResult - результат отправки на данный email адрес. Возможные значения:
pending - задание еще находится в очереди или по нему еще не завершена отправка письма. Вы можете запросить результат повторно позднее. sent - письмо было успешно отправлено. failed - письмо не было отправлено по причине ошибки доставки. Текст ошибки будет передан в параметре lastReply. excluded - письмо не было отправлено т.к. Email находился в Списке исключений или попал под Правила Исключений.
lastReply - последний ответ сервера. Будет содержать ошибку доставки если sendResult = failed
failCategory - если письмо не было отправлено (sendResult = failed) - данный параметр содержит категорию ошибки отправки. Возможные значения:
bad email - адрес получателя определился как "плохой" исходя из ошибки почтового сервера (ошибка содержала строку типа "user not found", полный перечень ошибок определения плохих адресов задается в окне Настройки->Smtp правила). refused content or IP - письмо не было доставлено из-за ошибки, связанной с блокировкой содержимого вашего письма или IP адреса. Полный перечень ошибок задается в окне Настройки->Smtp правила. other - ошибка отправки, связанная с не возможностью установить соединение, таймаутом соединения, или с ошибкой тип которой не удалось распознать с помощью правил, заданных в окне Настройки->Smtp правила. |
{ "jsonrpc":"2.0", "result":[ { "ID":"1", "Email":"billgates@microsoft.com", "sendResult":"sent", "lastReply":"250 DATA received; Message accepted" }, { "ID":"2", "Email":"jeffbezos@amazon.com", "sendResult":"failed", "lastReply":"500 Connect error - Winsock - Connection refused (#10061)", "failCategory":"other" } ], "id":1 } |
isSchedulerRunning |
Команда возвращает статус работы Планировщика рассылок. Может использоваться, к примеру, для контроля работы Планировщика после перезагрузки и/или обновлении операционной системы на сервере, где установлен AMS. Если Планировщик не запущен - запуск рассылок по расписанию не будет работать !
Описание параметров:
apiKey - ключ доступа к API |
Пример вызова:
{ "jsonrpc":"2.0", "method":"isSchedulerRunning", "params": {"apiKey": "38091FE7-5516-4F5B-9455-4A340BFEC875"}, "id":"1" } |
Результат вызова содержит состояние запуска Планировщика рассылок: true если запущен, false если нет: |
{ "jsonrpc":"2.0", "result":true, "id":1 } |
runScheduler |
Команда запускает Планировщик рассылок. Т.к. если Планировщик не запущен - запуск рассылок по расписанию не будет работать !
Описание параметров:
apiKey - ключ доступа к API |
Пример вызова:
{ "jsonrpc":"2.0", "method":"runScheduler", "params":{ "apiKey":"38091FE7-5516-4F5B-9455-4A340BFEC875" }, "id":"1" } |
Результат вызова содержит строку "ОК" или ошибку. |
{ "jsonrpc":"2.0", "result":"OK", "id":1 } |
