Вебхуки

  • webhook/set - установить/редактировать webhook
  • webhook/get - просмотреть установленный webhook
  • webhook/delete - удалить webhook

В процессе отправки и доставки письмо проходит через несколько статусов: (sent, delivered, opened, hard bounced, soft bounced, spam, clicked, unsubscribed).

Чтобы отслеживать изменения статусов отправленных писем с помощью API можно настроить webhook-и (обращение от UniOne на сайт клиента).

В результате настройки webhook-а при каждой отправке письма система будет генерировать запросы на сайт клиента, предоставляя данные об изменениях статусов отправленных писем, а также извещать о блокировке исходящего SMTP-сервера и блокировке домена на стороне получателя. В зависимости от настроек webhook-а система может уведомлять как об одном определенном статусе, так и о нескольких, или вообще о всех изменениях статуса письма. Система может присылать уведомления о блокировке SMTP-сервера (серверов) и блокировки отправки писем на определенный домен. Отслеживание изменения статусов email и оповещение об этом производится в течение 30 дней после отправки email.

Если URL, на который отправляется webhook, недоступен (отвечает не HTTP 200 OK, таймаут - 3 секунды), попытки отправки webhook на этот URL до получения ожидаемого 200 ОК будут продолжаться в течение 24 часов с интервалом в 10 минут с дополнительным параметром retry_count, значение которого будет увеличиваться на 1 с каждой повторной отправкой webhook.
 


Пример JSON оповещения

 

{  
   "auth":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "events_by_user":
   [  
      { 
        "user_id":1234,
        "project_id":"68234925084562", 
        "project_name":"MyProject", 
        "events":
        [  
          {  
            "event_name":"transactional_email_status",
            "event_data":
            {  
              "job_id":"1a3Q2V-0000OZ-S0",
              "metadata":
                {
                  "key1":"val1",
                  "key2":"val2",
                  "key3":"val3" 
                },
              "email":"recipient.email@example.com",
              "status":"sent",
              "event_time":"2015-11-30 15:09:42",
              "delivery_info": 
                {
                  "delivery_status": "err_delivery_failed",
                  "destination_response": "550 qa_spam_removed_simulation",
                  "user_agent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36",
                  "ip":"111.111.111.111"
                },
              "url":"http://some.url.com"
            }
          },
          {
            "event_name":"transactional_spam_block",
            "event_data":
            {
              "block_time":"YYYY-MM-DD HH:MM:SS",
              "block_type":"one_smtp",
              "domain":"domain_name", 
              "SMTP_blocks_count":8,
              "domain_status":"blocked"
            }
          },
          {
            "event_name":"email_check",
            "event_time":"2019-02-26 10:11:03",
            "event_data":
            {
              "email":"mail@domain.com",
              "is_checked":true
            }
          }
        ]
      }
   ]
}

где:

auth — это MD5-хэш строкового тела сообщения, в котором значение auth заменено на api_key пользователя, чей обработчик вызывается. С помощью этого получатель оповещения может как провести аутентификацию, так и проверить целостность оповещения;
user_id — идентификатор пользователя в системе;
project_id — идентификатор проекта, если webhook был зарегистрирован с помощью API-ключа проекта;
project_name — имя проекта, если webhook был зарегистрирован с помощью API-ключа проекта;
events — массив, содержащий события, присылаемые обработчиком;
event_name — тип возвращаемого события.

  • События типа email_status (значение устанавливалось при создании обработчика) возвращают значение transactional_email_status.
  • События типа spam_block возвращают значение transactional_spam_block;

event_data — массив, содержащий информацию о событии. В зависимости от типа возвращаемого события, этот массив будет отличаться полями:


 - Для transactional_email_status:
job_id — уникальный идентификатор письма, возвращаемый при отправке писем методом email/send;
email — адрес получателя;
status — статус, возвращаемый обработчиком (см. выше);
event_time — время возникновения события в формате “YYYY-MM-DD hh:mm:ss” по UTC;
delivery_info — объект, содержит детализированную информацию по доставке/недставке. Объект возвращается, если status будет hard_bounced, soft_bounced, opened, clicked:  
delivery_status — статус письма при недоставке (для "status" : "hard_bounced" и "status" : "soft_bounced");
destination_response — ответ SMTP сервера получателя (для "status" : "hard_bounced" and "status" : "soft_bounced");  
user_agent — информация про браузер и операционную систему получателя (for "status" : "opened" and "status" : "clicked");
ip — IP-адрес получателя (для "status" : "opened" и "status" : "clicked");


- Для transactional_spam_block:
block_time — время блокировки исходящего SMTP сервера;
block_type — может принимать значения one_smtp (при блокировке одного SMTP), all_smtp (при блокировке всех SMTP для домена получателя);
domain — имя домена получателя;
SMTP_blocks_count — счетчик, показывающий количество заблокированных SMTP;
domain_status — принимает значения blocked и unblocked (заблокирована отправка по данному домену, или нет соответственно).

Больше информации по спам-блокировкам здесь.