Webhook Methods

In the process of sending and delivery, the emails pass through several statuses: sent, delivered, opened, hard_bounced, soft_bounced, spam, clicked, unsubscribed.

In order to track changes in the status of a letter through an API, you can configure Webhooks (callbacks at the client's site).

When Webhook is enabled, every time you send a letter, the system will generate a request to the client’s site to obtain the status data of the sent messages and receive information about blocking the outgoing SMTP server and restricting sending to particular receivers’ domains. Depending on the WebHooks settings, the system can notify about one or more email statuses and spam blocks.

If the URL to which Webhook is sent is not available (the response is not HTTP 200 OK with 3 seconds timeout), the system will attempt to send Webhook to this URL (with an additional parameter retry_count that will be increasing by 1 with each request) until the expected 200 OK for 24 hours with 10 minutes interval.


Webhook JSON notification example

 

{  
   "auth":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "events_by_user":
   [  
      { 
        "user_id":456,
        "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
            }
          }
        ]
      }
   ]
}

where:

auth - MD5-hash of the message body, in which the value “auth” is replaced by “api_key” of the user; with this, the recipient of the notification can both authenticate and verify the notification integrity

user_id - user id;

project_name - name of the project, present only if webhook was registered for the project using project API key for user;

events - an array that contains events sent by webhook handler

event_name - type of returned notification:

  • transactional_email_status (for email_status - see webhook/set);

  • transactional_spam_block (for spam_block - see webhook/set);

event_data - an array containing information about the event. Depending on the type of the returned event, this array will have different fields:

 - for transactional_email_status:

job_id - unique letter identifier, returned by email/send;
email - recipient email address
status - returned email status (see above)
event_time - time of event occurrence in format “YYYY-MM-DD hh:mm:ss” UTC
delivery_info — an object that includes detailed delivery information. The object is returned if status is hard_bounced, soft_bounced, opened, clicked:  
delivery_status — email delivery status for bounces (for "status" : "hard_bounced" and "status" : "soft_bounced")  
destination_response — recipient's SMTP server response (for "status" : "hard_bounced" and "status" : "soft_bounced");  
user_agent — information about the browser and operating system (for "status" : "opened" and "status" : "clicked")
ip — recipient's IP address (for "status" : "opened" and "status" : "clicked")

 - for transactional_spam_block:

block_time - outgoing SMTP blocking time (UTC)
block_type - can return one_smtp (if a single SMTP was blocked), all_smtp (if all SMTP were blocked for the recipient’s domain)
domain - recipient’s domain name
SMTP_blocks_count - counter that shows the quantity of the blocked SMTP
domain_status - can return blocked or unblocked (shows whether the current domain is allowed to send to)
More information about spam blocks here