To use webhooks, you need to provide us with the URL where we will send responses with the message status.
GMS generates two types of events that have distinct record_name field and record_data structures:
- transactional_email_status – email delivery status change event. You can subscribe to selected statuses only
- transactional_spam_block – event of activating/deactivating a spam block for single or multiple SMTP servers.
{
"auth": "string",
"records_by_user": [
{
"user_id": "integer",
"project_id": "string",
"project_name": "string",
"records": [
{
"record_name": "string",
"record_data": {
"job_id": "1a3Q2V-0000OZ-S0",
"global_info": {
"key1": "val1",
"key2": "val2"
},
"email": "recipient.email@example.com",
"status": "sent",
"record_time": "2015-11-30 15:09:42", "url": "http://some.url.com",
"delivery_report": {
"delivery_report_status": "err_delivery_failed",
"destination_response": "550 Spam rejected",
"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"
}
}
},
{
"event_name": "transactional_spam_block",
"record_data": {
"spam_block_time": "YYYY-MM-DD HH:MM:SS",
"spam_block_type": "one_smtp",
"domain_blocker": "domain_name",
"SMTP_blocks_count": 8,
"domain_status": "blocked"
}
}
]
}
]
}Parameters
| Name | Type | Description |
|---|---|---|
| auth | STRING | MD5-hash of the message body, in which the value “auth” is replaced by api key of the user/project; with this field the recipient of the notification can both authenticate and verify the notification integrity |
| records_by_user | ARRAY REQUIRED | Array with only one element, containing events of a user/project. |
| »user_id | INTEGER REQUIRED | Unique user identifier. |
| »project_id | STRING | Project identifier, present only if webhook was registered for the project using project API key. |
| »project_name | STRING | Project name, present only if webhook was registered for the project using project API key. |
| »records | ARRAY REQUIRED | Array of events reported by webhook. |
| »»record_name | STRING | Type of record data contained in record_data field, either “transactional_email_status” or “transactional_spam_block”. |
| »»record_data | OBJECT | Object with different event properties depending on “record_name”. Below you can see all the properties, “transactional_email_status”-related first and then “transactional_spam_block”-related. |
| »»»job_id | STRING | Job identifier returned earlier by email/send method. Property exists only if record_name=“transactional_email_status”. |
| »»»global_info | OBJECT | Metadata passed in email/send method in records.global_info or global_metadata properties. This property exists only if record_name=“transactional_email_status”. |
| STRING (EMAIL) | Recipient’s email. This property exists only if record_name=“transactional_email_status”. | |
| »»»status | STRING | Email delivery status. This property exists only if record_name=“transactional_email_status”. Possible values are: accepted — the message has been accepted, but not sent yet. sent — the message has been sent, but not delivered yet. delivered — the message has been delivered. It can be changed to “opened”, “clicked”, “unsubscribed”, “subscribed” or “spam”. opened — the message has been delivered and read. It can be changed to “clicked”, “unsubscribed”, “subscribed” or “spam”. clicked — the message has been delivered, read, and at least one of the links in email has been clicked. It can be changed to “unsubscribed”, “subscribed” or “spam”. unsubscribed — the message has been delivered to the recipient and read, but then the recipient unsubscribed. It can be changed to “subscribed”. subscribed — the message has been delivered to the recipient and read, but then the recipient unsubscribed and subscribed again. It can be changed to “unsubscribed”. soft_bounced — temporary delivery failure. UniOne will try to deliver the message during 48 hours. In case of success the status changes to “delivered”, in case of failure to deliver during 48 hours message status changes to “hard_bounced”. hard_bounced — failed to deliver the message, there will be no delivery attempts. It’s a final status. There are a lot of possible reasons, you can use SMTP response from delivery_info.destination_response field or UniOne internal reason classification from delivery_info.delivery_status field to analyze the reason. spam — the message has been delivered, but it was reported as spam by the recipient. UniOne can receive and process the spam complaint from several domains, including msn.com, outlook.com, hotmail.com, live.com, ukr.net, yahoo.com, aol.com using FBL. |
| »»»record_time | STRING (utc-date-timE) | Event date & time in UTC time zone in “YYYY-MM-DD hh:mm:ss” format. This property exists only if record_name=“transactional_email_status”. |
| »»»url | STRING (uRI) | URL for “opened” and “clicked” statuses. This property exists only if record_name=“transactional_email_status”. |
| »»»delivery_report | OBJECT | Object with detailed delivery info.Event date & time in UTC time zone in “YYYY-MM-DD hh:mm:ss” format. This property exists only if webhook has delivery_report property set to 1 and record_name=“transactional_email_status”. |
| »»»»delivery_report_status | STRING | UniOne internal detailed delivery status. Some possible values are: err_user_unknown – email address doesn’t exist; err_user_inactive – email address isn’t used anymore; err_will_retry – email was temporary rejected, delivery will be retried later; err_mailbox_discarded – email address was active earlier, but now it’s deleted; err_mailbox_full – mailbox is full; err_spam_rejected – email was rejected as a spam; err_blacklisted – email was rejected because sender IP or sender domain is found in a black list; err_too_large – email size is over limit, according to recipient’s server; err_unsubscribed – email was unsubscribed; err_unreachable – numerous delivery failures lead to mark this email address as permanently unavailable; err_skip_letter – sending has been canceled because the email address is temporarily unavailable; err_domain_inactive – the domain does not accept mail or does not exist; err_destination_misconfigured – the domain does not accept mail due to incorrect settings on the recipient’s side, and the server’s response contains information about a cause that can be fixed (for example, an inoperative blacklist is used, etc.); err_delivery_failed – delivery failed due to other reasons; err_spam_skipped – sending has been canceled because the campaign has been blocked as a spam; err_lost – the message was not sent due to inconsistency of its parts or it has been lost because of the failure on our side. The sender needs to re-send the letter on his own, since the original has not been saved; We reserve the right to change or add internal delivery statuses as we need, so the following list is provided as an example only, without any description: ok_sent, ok_delivered, ok_read, ok_link_visited, ok_unsubscribed, ok_resubscribed, ok_spam_folder, ok_fbl, not_sent, skip_dup_unreachable, skip_dup_temp_unreachable, skip_dup_mailbox_full, err_spam_removed, err_resend, err_unknown, err_retry_letter, err_src_invalid, err_dest_invalid, err_not_available, err_internal, err_no_dns, err_no_smtp, err_giveup. |
| »»»»destination_response | STRING | SMTP response. |
| »»»»user_agent | STRING | User agent of recipient. Present only if detected for “clicked” and “opened” statuses. |
| »»»»ip | STRING | Recipient’s IP address. Present only if detected for “clicked” and “opened” statuses. |
| »»»spam_block_time | STRING (utc-date-timE) | Spam block date & time in UTC time zone in “YYYY-MM-DD hh:mm:ss” format. This property exists only if record_name=“transactional_spam_block”. |
| »»»spam_block_type | STRING | Spam block type, either single or multiple sending SMTP. For single sending SMTP block in common pool UniOne retries several other SMTPs. This property exists only if record_name=“transactional_spam_block”. |
| »»»domain_blocker | STRING | Domain that blocked sending. This property exists only if record_name=“transactional_spam_block”. |
| »»»SMTP_blocks_count | INTEGER | Number of sending SMTPs blocked. This property exists only if record_name=“transactional_spam_block”. |
| »»»domain_status | STRING | Whether it’s a block or unblock event. This property exists only if record_name=“transactional_spam_block”. |