docs(tem): webhook events payload (#3734)

managed-services/transactional-email/api-cli/webhook-events-payloads.mdx

@@ -0,0 +1,181 @@
+---
+meta:
+  title: Understanding Webhook event payloads
+  description: This page details the fields of the webhook event payloads for Scaleway Transactional Email
+content:
+  h1: Understanding Webhook event payloads
+  paragraph: This page details the fields of the webhook event payloads for Scaleway Transactional Email
+tags: spf dkim dmarc transactional
+dates:
+  validation: 2024-09-20
+  posted: 2024-09-20
+categories:
+  - managed-services
+---
+
+Events triggered by webhooks contain payloads that describe and detail the events.
+
+Find below a detailed description of the fields in a [Webhoook event](/managed-services/transactional-email/how-to/create-webhooks/) payload.
+
+
+| Tag     | Description    |
+|---------|-------------------------------------|
+| `id`     | Event identifier                                                                          |
+| `type`     | Event type                                      |
+| `organization_id`    | Domain Organization                            |
+| `project_id` | Domain Project                                                       |
+| `domain_id`  | Domain identifier                                                       |
+| `domain_name`   | Domain name  |
+| `created_at`    | Event creation date. Dates should be included in RFC-3339 format.                           |
+| `email_sent_at`    | 	Email reception date by the recipient server. Dates should be included in RFC-3339 format.                     |
+| `email_queued_at` | Email reception date by TEM proxy or API. Dates should be included in RFC-3339 format.                                                          |
+| `email_id`  | Email identifier (used for GetEmail endpoint)                                                      |
+| `email_from`   | Email FROM address |
+| `email_to`  | Email recipient address                                                          |
+| `email_headers`   | SMTP headers  |
+| `email_error`   | SMTP message explaining the drop  |
+| `email_next_try`   | Next time the email will be sent to the recipient server  |
+| `email_try_count`   | Total number of tries attempted for this email  |
+
+
+## Examples of payload by event type
+
+Webhooks may trigger different [types of events](/managed-services/transactional-email/concepts/#webhook-event-type). These types have varying payload fields.
+
+## email_queued
+```json
+{
+  "id": string,
+  "type": "email_queued",
+  "organization_id": string,
+  "project_id": string,
+  "domain_id": string,
+  "domain_name": string,
+  "created_at": date,
+  "email_queued_at": date,
+  "email_id": string,
+  "email_from": string,
+  "email_to": string,
+  "email_headers": [
+    {
+      "name": string,
+      "value": string
+    }
+  ]
+}
+```
+## email_dropped
+```json
+{
+  "id": string,
+  "type": "email_dropped",
+  "organization_id": string,
+  "project_id": string,
+  "domain_id": string,
+  "domain_name": string,
+  "created_at": date,
+  "email_sent_at": date,
+  "email_id": string,
+  "email_from": string,
+  "email_to": string,
+  "email_headers": [
+    {
+      "name": string,
+      "value": string
+    }
+  ],
+  "email_error": string,
+}
+```
+## email_delivered
+```json
+{
+  "id": string,
+  "type": "email_delivered",
+  "organization_id": string,
+  "project_id": string,
+  "domain_id": string,
+  "domain_name": string,
+  "created_at": date,
+  "email_sent_at": date,
+  "email_id": string,
+  "email_from": string,
+  "email_to": string,
+  "email_headers": [
+    {
+      "name": string,
+      "value": string
+    }
+  ]
+}
+```
+## email_mailbox_not_found
+```json
+{
+  "id": string,
+  "type": "email_mailbox_not_found",
+  "organization_id": string,
+  "project_id": string,
+  "domain_id": string,
+  "domain_name": string,
+  "created_at": date,
+  "email_sent_at": date,
+  "email_id": string,
+  "email_from": string,
+  "email_to": string,
+  "email_headers": [
+    {
+      "name": string,
+      "value": string
+    }
+  ]
+}
+```
+## email_spam
+```json
+{
+  "id": string,
+  "type": "email_spam",
+  "organization_id": string,
+  "project_id": string,
+  "domain_id": string,
+  "domain_name": string,
+  "created_at": date,
+  "email_sent_at": date,
+  "email_id": string,
+  "email_from": string,
+  "email_to": string,
+  "email_headers": [
+    {
+      "name": string,
+      "value": string
+    }
+  ]
+}
+```
+## email_deferred
+```json
+{
+  "id": string,
+  "type": "email_deferred",
+  "organization_id": string,
+  "project_id": string,
+  "domain_id": string,
+  "domain_name": string,
+  "created_at": date,
+  "email_sent_at": date,
+  "email_id": string,
+  "email_from": string,
+  "email_to": string,
+  "email_headers": [
+    {
+      "name": string,
+      "value": string
+    }
+  ],
+  "email_error": string,
+  "email_next_try": date,
+  "email_try_count": integer
+}
+```
+

menu/navigation.json

@@ -2401,6 +2401,10 @@
                   {
                     "label": "Setting up and using TEM webhooks with SNS topics",
                     "slug": "use-webhooks-with-sns-topics"
+                  },
+                  {
+                    "label": "Understanding Webhook event payloads",
+                    "slug": "webhook-events-payloads"
                   }
                 ],
                 "label": "API/CLI",
@@ -5329,4 +5333,4 @@
     ],
     "label": "Additional Services"
   }
-]
+]