Update 'Webhook Events & Payloads'

2024-06-11 15:12:29 +07:00 · 2024-06-11 15:12:29 +07:00 · 1a562f9ae7
commit 1a562f9ae7
parent cb776fece4
1 changed files with 139 additions and 0 deletions
--- a/Webhook-Events-%26-Payloads.md
+++ 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"
+  },
+}
+```