APITRANZ, 1.0 2020-08-17

Формат протокола

Запрос

Адрес для вызова

URL вызова указан в его описании

Слово ACCOUNT в нём - код вашего аккаунта.

Метод вызова

Транспорт - HTTP 1.0/1.1 over TLSv1.2 - RFC 2616 http://tools.ietf.org/html/rfc2616, RFC 5246 http://tools.ietf.org/html/rfc5246

Основной протокол - TLSv1.2

Рекомендуемые расширения - SNI и NPN/ALPN

Настоятельно рекомендуется использовать Keep-Alive для получения лучшей пропускной способности.

Имя trapi.sendsay.ru имеет несколько ip-адресов. При невозможности соединения с каким-то из этих адресов необходимо повторять запрос с использованием других.

Вы можете получить api-ошибку rate_limit, HTTP код ответа 503, тайм-аут запроса - в зависимости от отношения системы к текущему превышению лимита коннектов и их скорости.

Вы можете получить HTTP код ответа 502 или 504 при запросах длительность обработки которых превышет лимит.

Метод вызова - POST - RFC 2616 section 5 https://tools.ietf.org/html/rfc2616#section-9.5

Максимальный размер запроса - в настоящий момент 25 Мбайт.

Content-Type: запроса - application/json

Содержимое запроса - JSON-строка в кодировке UTF-8.

{
 "action" : "код вызываемого действия" -- обязательно

 прочие парметры, если нужны
}

Описание формата JSON вы найдёте в RFC 7159 http://tools.ietf.org/html/rfc7159

Не забывайте кодировать символы которые не могут быть непосредственно записаны в JSON.

"Красивое" форматирование пробелами совершенно не обязательно и его отсутствие может заметно уменьшить размер вашего запроса, что увеличит скорость его обработки.

Настоятельно рекомендуется пользоваться готовыми функциями вашего языка программирования для перевода структуры данных в json-строку.

Обширная практика службы поддержки показывает, что самостоятельная реализация json-кодирования может привести к значительной переоценке своих навыков программирования в строну уменьшения и последующей депрессии на этой почве.

Ответ

JSON-строка в кодировке UTF-8

Нормальный ответ


{

 <общие поля>

,<поля специфические для конкретного запроса>

}

Формат ответа при ошибке

При наличии ошибки (ошибок) препятствующих полному или частичному выполнению запроса в ответе появится массив errors со списком описаний каждой ошибки.

Обратите внимание, что, зависимости от вызова и самой ошибки, поле explain может быть не только строкой, но и массивом и объектом.

Часть вызовов может возвращать массив warnings аналогичный структуры для того что бы сообщить о событиях помешавших выполнить вызов в какой-либо его части, но не позволяющих считать что вызов ошибочен.

{

 <общие поля>

."errors" :  [
              {
               "id" : "код ошибки-1" 

              ,"explain" : "возможное более развёрнутое описание-1" 

              ,<возможно поля специфические для конкретного запроса-1>
              }
             ,{
               "id" : "код ошибки-2" 

              ,"explain" : "возможное более развёрнутое описание-2" 

              ,<возможно поля специфические для конкретного запроса-2>
              }

              ......

             ]
}

Отправить письмо

Адрес вызова

https://trapi.sendsay.ru/tranz/api/v2/ACCOUNT/json/issue.send/personal

Запрос

{
   "apikey" : "ключ апи. выдаётся в основном api" 

  ,"action" : "issue.send" 

  ,"group"  : "personal" 

  ,"uuid" : "клиентский идентификатор письма" -- строка до 255 символов. А-Za-z0-9=_-  если не указан или пустой, то будет назначен автоматически
                                              -- используется для идентификации письма при получении статистики в основном api

  ,"label" : "метка" или [ "метка1", "метка2".. ] -- набор произвольных меток выпуска позволяющих выпуск фильтровать/классифицировать в основном api
                                                  -- от 0 до 2 строк не длиннее 32 байт
                                                  -- необязательно

  ,"lbac.id" : номер политики из основного api для назначения доступа по LBAC 

-- указание содержимого письма, одно из

  ,"letter" : {

                "subject" : "Тема письма" -- обязательно не пусто

               ,"from.name" : "Имя отправителя" 

               ,"from.email" : "Адрес отправителя (email)" -- обязательно не пусто

               ,"reply.name" : "Имя для обратного адреса для ответа" 

               ,"reply.email" : "Обратный адрес для ответа (email)" 

               ,"to.name" : "Имя получателя" 

               ,"message" : { -- одна или обе не пустые версии письма

                           "html" : "html-версия письма" 

                          ,"amp" : "amp-версия письма" 

                          ,"text" : "текстовая версия письма" 
                          }

                * прикреплённые файлы письма

                -- по умолчанию, mime-тип файла определяется по расширению

                -- по умолчанию, кодировкой текстовых файлов text/* считается utf-8

               ,"attaches" : [ 

                             {
                              "name" : "имя файла",

                             ,"content": "содержимое файла закодированное base64",

                             ,"encoding" : "base64",

                             ,"mime-type" : "тип атача", -- не обязательно, заменяет тип установленный по расширению имени атача

                             ,"charset" : "набор символов атача", -- не обязательно, заменяет используемое по умолчанию utf-8
                             }

                             ......
                          ]
               }

-- или

  ,"letter" : {

               "draft.id" : "номер или алиас черновика" 

              ,"attaches" : [
                              -- дополнительные прикрепляемые файлы
                              -- добавляются к тем, что, возможно, есть в черновике 
                            ]

              }

   ,"email" : "адрес получателя" -- обязательно, не пусто

   ,"email.fake" : "адрес для учёта" -- если не пусто, то именно этот адрес будет занесён в систему и будет фигурировать в отчётах
                                     -- таким образом вы можете дополнительно обезопасить себя - в системе не будут храниться реальный адрес
                                     -- данный адрес так же как и указанный в email проверяется на нахождение в стоп-листе и отписки

   ,"ttl" : "положительное число" -- время попыток доставить письмо
                                  -- по умолчанию 4 дня если иное не указано в черновике или в аккаунте

   ,"dkim.id" : "идентификатор DKIM для подписи письма" 

   ,"relink" :  0|1 -- Преобразовывать ссылки автоматически. По умолчанию - 0, НЕ преобразовывать, что отлично от обычного api
                   -- 1 - да, 0 - нет

    -- данные персонализации
    -- для совместимости с полным API индивидуальные данные получателя должны содержать в ключе anketa
    -- по сравнению с полным API не работают функции: countup, countdown, draw_graph, lenta_get, geturl

    ,"extra" : {
                "anketa" : {
                            "val" : 5        -- [% anketa.val.5 %]
                           ,"arr" : [ 8 ,9 ] -- [% anketa.arr[1] %]
                           ,"hash" : { "qwerty" : "йцукен"} -- [% anketa.hash.asdf %]
                           }
                .............
               }

}

Ответ

{
 "uuid" : "идентификатор письма" -- копия входного значения или автоматически назначеный
}

Возможные ошибки

cant_decode - не удалось разобрать json или он не объект

internal_write - внутренние проблемы

wrong_uuid - клиентский uuid длиннее 255 или содержит левые символы

wrong_apikey - ошибка в apikey

wrong_email - ошибка в адресе получателя

wrong_email.fake - ошибка в адресе для учёта

wrong_group - ошибка в group

unknown_draft - указан неизвестный черновик

draft_isnt_filled_completely - в черновике заполнены не все поля обязательные для выпуска

issue_vs_draft_channel_missmatch - черновик не предназначен для канала email

wrong_label_more_2 - меток выпуска больше двух

wrong_label_toolong_0 - слишком длинная метка 0

wrong_label_toolong_1 - слишком длинная метка 1

Специфические кода ошибок доставки (все фатальны) которые могут быть с статистике результатов доставки (основное api)

5.5.0 - адрес имеет постоянные ошибки доставки или в стоп-листе

6.6.5 - проблема формирования письма, подробности в тексте ошибки

6.7.0 - месячный лимит писем исчерпан

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

Адрес вызова

https://trapi.sendsay.ru/tranz/api/v2/ACCOUNT/json.batch/issue.send/personal

Запрос

{
   "apikey" : "............." -- именно тут ! а не внутри каждого задания

  ,"uuid" : "идентификатор запроса" -- не обязательно, просто для облегчения возможно отладки
                                    -- НЕ заменяет собой индивидульный uuid каждого задания

  ,"action" : "batch" 

  ,"do" : [  -- ошибка одного задания ни как не влиеят на другие задания - они продолжают обрабатываться
           { одно задание как при выхзове issue.send }
          ,{ другое задание как при выхзове issue.send }
          ....
          ]

}

Ответ

{
 "result" : [
             { ответ (возможно с ошибкой) на одно задание как #11161 }
            ,{ ответ (возможно с ошибкой) на другое задание как #11161 }
            ............
            ]
}

Возможные ошибки

специфические ошибки всего вызова

wrong_do - параметр do не массив

специфические ошибки конкретной задачи

wrong_task - задание не объект

Общие замечания

Ошибки, опечатки, не соответствия

В данном документе могут быть ошибки и опечатки. Реальное поведение API может иногда отличаться от описанного.

При доработке и изменении API мы оставляем обратную совместимость (на время или на всегда), но при исправлении ошибок вида "поведение API не соответствует документации" такого не происходит, так как исправляется явная ошибка.

Если реальное поведение API отличается от описанного здесь, то настоятельно рекомендуется не ориентироваться на "то что есть", а связаться с нами написав на ask@sendsay.ru сообщение о найденной проблеме.

Ближайшие не совместимые изменения

Нет.

История изменений

1.0     2020-07-17      * Первоначальное описание