diff --git a/Webhook-Events-%26-Payloads.md b/Webhook-Events-%26-Payloads.md new file mode 100644 index 0000000..dcafd31 --- /dev/null +++ b/Webhook-Events-%26-Payloads.md @@ -0,0 +1,139 @@ +# Webhook Events & Payloads + +This page lists all the different types of event along with an example JSON payload that you'll receive. In many cases, only a small amount of information will be sent, if you require more information you should use our API to get it. + +# Message Status Events + +These events all receive the same payload (with different data) based on the status of a message. + +* `MessageSent` - when a message is successfully delivered to a recipient/endpoint. +* `MessageDelayed` - when a message's delivery has been delayed. This will be sent each time we attempt a delivery and a message is delayed further. +* `MessageDeliveryFailed` - when a message cannot be delivered. +* `MessageHeld` - when a message is held. + +```javascript +{ + "status":"Sent", + "details":"Message sent by SMTP to aspmx.l.google.com (2a00:1450:400c:c0b::1b) (from 2a00:67a0:a:15::2)", + "output":"250 2.0.0 OK 1477944899 ly2si31746747wjb.95 - gsmtp", + "time":0.22, + "sent_with_ssl":true, + "timestamp":1477945177.12994, + "message":{ + "id":12345, + "token":"abcdef123", + "direction":"outgoing", + "message_id":"5817a64332f44_4ec93ff59e79d154565eb@app34.mail", + "to":"test@example.com", + "from":"sales@awesomeapp.com", + "subject":"Welcome to AwesomeApp", + "timestamp":1477945177.12994, + "spam_status":"NotSpam", + "tag":"welcome" + } +} +``` + +# Message Bounces + +If we receive a bounce message for a message that was previously accepted, you'll receive the `MessageBounced` event. + +```javascript +{ + "original_message":{ + "id":12345, + "token":"abcdef123", + "direction":"outgoing", + "message_id":"5817a64332f44_4ec93ff59e79d154565eb@app34.mail", + "to":"test@example.com", + "from":"sales@awesomeapp.com", + "subject":"Welcome to AwesomeApp", + "timestamp":1477945177.12994, + "spam_status":"NotSpam", + "tag":"welcome" + }, + "bounce":{ + "id":12347, + "token":"abcdef124", + "direction":"incoming", + "message_id":"5817a64332f44_4ec93ff59e79d154565eb@someserver.com", + "to":"abcde@amrp.prmail.vn", + "from":"postmaster@someserver.com", + "subject":"Delivery Error", + "timestamp":1477945179.12994, + "spam_status":"NotSpam", + "tag":null + } +} +``` + +# Message Click Event + +If you have click tracking enabled, the `MessageLinkClicked` event will tell you that a user has clicked on a link in one of your e-mails. + +```javascript +{ + "url":"https://prmail.vn", + "token":"VJzsFA0S", + "ip_address":"185.22.208.2", + "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36", + "message":{ + "id":12345, + "token":"abcdef123", + "direction":"outgoing", + "message_id":"5817a64332f44_4ec93ff59e79d154565eb@app34.mail", + "to":"test@example.com", + "from":"sales@awesomeapp.com", + "subject":"Welcome to AwesomeApp", + "timestamp":1477945177.12994, + "spam_status":"NotSpam", + "tag":"welcome" + } +} +``` + +# Send Limit Events + +You can subscribe to receive information when your server is approaching/exceeded its [send limit](^/sending-messages/send-limits). There are two events you can subscribe to for this: + +* `SendLimitApproaching` - shortly after your server reaches 90% of its limit. +* `SendLimitExceeded` - shortly after your server exceeded its limit. + +```javascript +{ + "server":{ + "uuid":"54529725-8807-4069-ab29-a3746c1bbd98", + "name":"AwesomeApp Mail Server", + "permalink":"awesomeapp", + "organization":"prmail" + }, + "volume":904, + "limit":1000 +} +``` + +# DNS Error Event + +We constantly monitor your domains to ensure that your SPF/DKIM/MX records are correct. If you'd like to be notified when our checks fail, you can subscribe to the `DomainDNSError` event. + +```javascript +{ + "domain":"example.com", + "uuid":"820b47a4-4dfd-42e4-ae6a-1e5bed5a33fd", + "dns_checked_at":1477945711.5502, + "spf_status":"OK", + "spf_error":null, + "dkim_status":"Invalid", + "dkim_error":"The DKIM record at example.com does not match the record we have provided. Please check it has been copied correctly.", + "mx_status":"Missing", + "mx_error":null, + "return_path_status":"OK", + "return_path_error":null, + "server":{ + "uuid":"54529725-8807-4069-ab29-a3746c1bbd98", + "name":"AwesomeApp Mail Server", + "permalink":"awesomeapp", + "organization":"prmail" + }, +} +``` \ No newline at end of file