From ef2500df5f4c8e671865163b4ce5ce417582a9e9 Mon Sep 17 00:00:00 2001 From: ldecarvalho-doc <82805470+ldecarvalho-doc@users.noreply.github.com> Date: Fri, 20 Sep 2024 15:14:58 +0200 Subject: [PATCH 1/9] docs(tem): payload --- .../api-cli/webhook-events-payload.mdx | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 managed-services/transactional-email/api-cli/webhook-events-payload.mdx diff --git a/managed-services/transactional-email/api-cli/webhook-events-payload.mdx b/managed-services/transactional-email/api-cli/webhook-events-payload.mdx new file mode 100644 index 0000000000..230294557e --- /dev/null +++ b/managed-services/transactional-email/api-cli/webhook-events-payload.mdx @@ -0,0 +1,151 @@ +--- +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 spf-record dkim dkim-records dmarc dmarc-record 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 | +| `email_sent_at` | Email reception date by the recipient server | +| `email_queued_at` | Email reception date in by TEM proxy or API | +| `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 we will try to send the email 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": string, + "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": string, + "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": string, + "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": string, + "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": string, + "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": string, + "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 +} +``` + From f382a4045d1c7d4d28b4c2b2c7274b147900793c Mon Sep 17 00:00:00 2001 From: ldecarvalho-doc <82805470+ldecarvalho-doc@users.noreply.github.com> Date: Fri, 20 Sep 2024 15:16:41 +0200 Subject: [PATCH 2/9] docs(tem): menu --- menu/navigation.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/menu/navigation.json b/menu/navigation.json index 17d940b0e0..dd9a74d294 100644 --- a/menu/navigation.json +++ b/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": "webhooks-events-payload" } ], "label": "API/CLI", @@ -5329,4 +5333,4 @@ ], "label": "Additional Services" } -] +] \ No newline at end of file From 856f31aef74f2a130180aa781133d6b4cb5dff0c Mon Sep 17 00:00:00 2001 From: Benedikt Rollik Date: Mon, 23 Sep 2024 13:43:18 +0200 Subject: [PATCH 3/9] Update managed-services/transactional-email/api-cli/webhook-events-payload.mdx Co-authored-by: Jessica <113192637+jcirinosclwy@users.noreply.github.com> --- .../transactional-email/api-cli/webhook-events-payload.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managed-services/transactional-email/api-cli/webhook-events-payload.mdx b/managed-services/transactional-email/api-cli/webhook-events-payload.mdx index 230294557e..38528cb3d9 100644 --- a/managed-services/transactional-email/api-cli/webhook-events-payload.mdx +++ b/managed-services/transactional-email/api-cli/webhook-events-payload.mdx @@ -5,7 +5,7 @@ meta: content: h1: Understanding Webhook event payloads paragraph: This page details the fields of the webhook event payloads for Scaleway Transactional Email -tags: spf spf-record dkim dkim-records dmarc dmarc-record transactional +tags: spf dkim dmarc transactional dates: validation: 2024-09-20 posted: 2024-09-20 From 95950ab16fdf5b11aa5d1e0ab6f1002f6bdb8be8 Mon Sep 17 00:00:00 2001 From: ldecarvalho-doc <82805470+ldecarvalho-doc@users.noreply.github.com> Date: Mon, 23 Sep 2024 14:33:06 +0200 Subject: [PATCH 4/9] fix(mdb): review jj et maxence Co-authored-by: Maxence Moutoussamy Co-authored-by: jerjako --- .../api-cli/webhook-events-payload.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/managed-services/transactional-email/api-cli/webhook-events-payload.mdx b/managed-services/transactional-email/api-cli/webhook-events-payload.mdx index 38528cb3d9..46055308b8 100644 --- a/managed-services/transactional-email/api-cli/webhook-events-payload.mdx +++ b/managed-services/transactional-email/api-cli/webhook-events-payload.mdx @@ -28,13 +28,13 @@ Find below a detailed description of the fields in a [Webhoook event](/managed-s | `domain_name` | Domain name | | `created_at` | Event creation date | | `email_sent_at` | Email reception date by the recipient server | -| `email_queued_at` | Email reception date in by TEM proxy or API | +| `email_queued_at` | Email reception date by TEM proxy or API | | `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 we will try to send the email to the recipient server | +| `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 | @@ -51,12 +51,15 @@ Webhooks may trigger different [types of events](/managed-services/transactional "project_id": string, "domain_id": string, "domain_name": string, - "created_at": string, + "created_at": date, "email_queued_at": date, "email_id": string, "email_from": string, "email_to": string, - "email_headers": [{"name": string, "value": string}], + "email_headers": [{ + "name": string, + "value": string + }], } ``` ## email_dropped @@ -68,7 +71,7 @@ Webhooks may trigger different [types of events](/managed-services/transactional "project_id": string, "domain_id": string, "domain_name": string, - "created_at": string, + "created_at": date, "email_sent_at": date, "email_id": string, "email_from": string, From 0bdb26bd559e91ed7c1a0028337b4ffc632da178 Mon Sep 17 00:00:00 2001 From: ldecarvalho-doc <82805470+ldecarvalho-doc@users.noreply.github.com> Date: Mon, 23 Sep 2024 14:57:24 +0200 Subject: [PATCH 5/9] fix(mdb): indentation --- .../api-cli/webhook-events-payload.mdx | 185 ++++++++++-------- 1 file changed, 106 insertions(+), 79 deletions(-) diff --git a/managed-services/transactional-email/api-cli/webhook-events-payload.mdx b/managed-services/transactional-email/api-cli/webhook-events-payload.mdx index 46055308b8..0bfa34b9c3 100644 --- a/managed-services/transactional-email/api-cli/webhook-events-payload.mdx +++ b/managed-services/transactional-email/api-cli/webhook-events-payload.mdx @@ -45,110 +45,137 @@ Webhooks may trigger different [types of events](/managed-services/transactional ## 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 - }], + "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, + "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": string, - "email_sent_at": date, - "email_id": string, - "email_from": string, - "email_to": string, - "email_headers": [{"name": string, "value": string}], + "id": string, + "type": "email_delivered", + "organization_id": string, + "project_id": string, + "domain_id": string, + "domain_name": string, + "created_at": string, + "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": string, - "email_sent_at": date, - "email_id": string, - "email_from": string, - "email_to": string, - "email_headers": [{"name": string, "value": string}], + "id": string, + "type": "email_mailbox_not_found", + "organization_id": string, + "project_id": string, + "domain_id": string, + "domain_name": string, + "created_at": string, + "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": string, - "email_sent_at": date, - "email_id": string, - "email_from": string, - "email_to": string, - "email_headers": [{"name": string, "value": string}], + "id": string, + "type": "email_spam", + "organization_id": string, + "project_id": string, + "domain_id": string, + "domain_name": string, + "created_at": string, + "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": string, - "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 + "id": string, + "type": "email_deferred", + "organization_id": string, + "project_id": string, + "domain_id": string, + "domain_name": string, + "created_at": string, + "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 } ``` From bbd04ec6a40275557a0aa06af4564476c1c287a3 Mon Sep 17 00:00:00 2001 From: ldecarvalho-doc <82805470+ldecarvalho-doc@users.noreply.github.com> Date: Mon, 23 Sep 2024 15:00:17 +0200 Subject: [PATCH 6/9] fix(mdb): date format --- .../transactional-email/api-cli/webhook-events-payload.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/managed-services/transactional-email/api-cli/webhook-events-payload.mdx b/managed-services/transactional-email/api-cli/webhook-events-payload.mdx index 0bfa34b9c3..a1a8590eb4 100644 --- a/managed-services/transactional-email/api-cli/webhook-events-payload.mdx +++ b/managed-services/transactional-email/api-cli/webhook-events-payload.mdx @@ -26,9 +26,9 @@ Find below a detailed description of the fields in a [Webhoook event](/managed-s | `project_id` | Domain Project | | `domain_id` | Domain identifier | | `domain_name` | Domain name | -| `created_at` | Event creation date | -| `email_sent_at` | Email reception date by the recipient server | -| `email_queued_at` | Email reception date by TEM proxy or API | +| `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 | From 2084d5f458f9612cbf544e0a96ff19150340ae25 Mon Sep 17 00:00:00 2001 From: ldecarvalho-doc <82805470+ldecarvalho-doc@users.noreply.github.com> Date: Mon, 23 Sep 2024 15:08:06 +0200 Subject: [PATCH 7/9] fix(mdb): date format --- ...ayload.mdx => webhook-events-payloads.mdx} | 24 +++++++++---------- menu/navigation.json | 2 +- 2 files changed, 13 insertions(+), 13 deletions(-) rename managed-services/transactional-email/api-cli/{webhook-events-payload.mdx => webhook-events-payloads.mdx} (94%) diff --git a/managed-services/transactional-email/api-cli/webhook-events-payload.mdx b/managed-services/transactional-email/api-cli/webhook-events-payloads.mdx similarity index 94% rename from managed-services/transactional-email/api-cli/webhook-events-payload.mdx rename to managed-services/transactional-email/api-cli/webhook-events-payloads.mdx index a1a8590eb4..51d5553ae1 100644 --- a/managed-services/transactional-email/api-cli/webhook-events-payload.mdx +++ b/managed-services/transactional-email/api-cli/webhook-events-payloads.mdx @@ -58,8 +58,8 @@ Webhooks may trigger different [types of events](/managed-services/transactional "email_to": string, "email_headers": [ { - "name": string, - "value": string + "name": string, + "value": string } ] } @@ -80,8 +80,8 @@ Webhooks may trigger different [types of events](/managed-services/transactional "email_to": string, "email_headers": [ { - "name": string, - "value": string + "name": string, + "value": string } ], "email_error": string, @@ -103,8 +103,8 @@ Webhooks may trigger different [types of events](/managed-services/transactional "email_to": string, "email_headers": [ { - "name": string, - "value": string + "name": string, + "value": string } ] } @@ -125,8 +125,8 @@ Webhooks may trigger different [types of events](/managed-services/transactional "email_to": string, "email_headers": [ { - "name": string, - "value": string + "name": string, + "value": string } ] } @@ -147,8 +147,8 @@ Webhooks may trigger different [types of events](/managed-services/transactional "email_to": string, "email_headers": [ { - "name": string, - "value": string + "name": string, + "value": string } ] } @@ -169,8 +169,8 @@ Webhooks may trigger different [types of events](/managed-services/transactional "email_to": string, "email_headers": [ { - "name": string, - "value": string + "name": string, + "value": string } ], "email_error": string, diff --git a/menu/navigation.json b/menu/navigation.json index dd9a74d294..041516fbe7 100644 --- a/menu/navigation.json +++ b/menu/navigation.json @@ -2404,7 +2404,7 @@ }, { "label": "Understanding Webhook event payloads", - "slug": "webhooks-events-payload" + "slug": "webhooks-events-payloads" } ], "label": "API/CLI", From d9729ba19b2945b22bfb3543841d2b4dbd621125 Mon Sep 17 00:00:00 2001 From: ldecarvalho-doc <82805470+ldecarvalho-doc@users.noreply.github.com> Date: Mon, 23 Sep 2024 15:11:45 +0200 Subject: [PATCH 8/9] fix(tem): review jj Co-authored-by: jerjako --- .../api-cli/webhook-events-payloads.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/managed-services/transactional-email/api-cli/webhook-events-payloads.mdx b/managed-services/transactional-email/api-cli/webhook-events-payloads.mdx index 51d5553ae1..bd4d9864f0 100644 --- a/managed-services/transactional-email/api-cli/webhook-events-payloads.mdx +++ b/managed-services/transactional-email/api-cli/webhook-events-payloads.mdx @@ -96,7 +96,7 @@ Webhooks may trigger different [types of events](/managed-services/transactional "project_id": string, "domain_id": string, "domain_name": string, - "created_at": string, + "created_at": date, "email_sent_at": date, "email_id": string, "email_from": string, @@ -118,7 +118,7 @@ Webhooks may trigger different [types of events](/managed-services/transactional "project_id": string, "domain_id": string, "domain_name": string, - "created_at": string, + "created_at": date, "email_sent_at": date, "email_id": string, "email_from": string, @@ -140,7 +140,7 @@ Webhooks may trigger different [types of events](/managed-services/transactional "project_id": string, "domain_id": string, "domain_name": string, - "created_at": string, + "created_at": date, "email_sent_at": date, "email_id": string, "email_from": string, @@ -162,7 +162,7 @@ Webhooks may trigger different [types of events](/managed-services/transactional "project_id": string, "domain_id": string, "domain_name": string, - "created_at": string, + "created_at": date, "email_sent_at": date, "email_id": string, "email_from": string, From a619a587c3db47b15c17d7fd4b9995bc2f4df17b Mon Sep 17 00:00:00 2001 From: ldecarvalho-doc <82805470+ldecarvalho-doc@users.noreply.github.com> Date: Mon, 23 Sep 2024 15:22:36 +0200 Subject: [PATCH 9/9] fix(mdb): menu --- menu/navigation.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/menu/navigation.json b/menu/navigation.json index 041516fbe7..fb2094af56 100644 --- a/menu/navigation.json +++ b/menu/navigation.json @@ -2404,7 +2404,7 @@ }, { "label": "Understanding Webhook event payloads", - "slug": "webhooks-events-payloads" + "slug": "webhook-events-payloads" } ], "label": "API/CLI",