From e93735cbc696d6ab07fd7dceda7e9380672820e9 Mon Sep 17 00:00:00 2001
From: C T <215163593+catplat@users.noreply.github.com>
Date: Mon, 6 Apr 2026 14:16:07 -0400
Subject: [PATCH 1/9] feat(platform): add email observability topic

Adds a new topic covering the SendGrid Overwatch API for monitoring
email delivery from Platform.sh environments.

Closes #5524

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/development/email-observability.md    | 139 ++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 sites/platform/src/development/email-observability.md

diff --git a/sites/platform/src/development/email-observability.md b/sites/platform/src/development/email-observability.md
new file mode 100644
index 0000000000..67e510439b
--- /dev/null
+++ b/sites/platform/src/development/email-observability.md
@@ -0,0 +1,139 @@
+---
+title: Monitor email delivery
+weight: 10
+sidebarTitle: Monitor email delivery
+description: Query delivery logs, statistics, and suppression lists for emails sent from your {{% vendor/name %}} environments.
+---
+
+{{% vendor/name %}} provides an email observability API that lets you inspect the delivery history
+and health of emails sent from your projects.
+You can use it to diagnose delivery failures, review bounce and block lists, and pull aggregated sending statistics.
+
+This API sits on top of the SendGrid infrastructure used by {{% vendor/name %}}'s
+[built-in SMTP proxy](/development/email.md).
+It doesn't provide direct access to SendGrid — all data is scoped to the projects your token is authorized for.
+
+## Authentication
+
+All requests require a short-lived OAuth2 access token passed as a Bearer token.
+You can access data only for projects listed in your token's claims.
+
+To get an access token:
+
+1. [Create an API token](/administration/cli/api-tokens.md) in the {{% vendor/name %}} Console.
+2. Exchange it for an access token (valid for 15 minutes):
+
+   ```bash
+   curl -u platform-api-user: \
+     -d 'grant_type=api_token&api_token={{< variable "API_TOKEN" >}}' \
+     https://auth.api.platform.sh/oauth2/token
+   ```
+
+   Use the `access_token` value from the response as the Bearer token in your requests.
+
+## Query message history
+
+Retrieve a log of delivery events for a project:
+
+```bash
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/get/{{< variable "PROJECT_ID" >}}" \
+  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
+  -H "accept: application/json" | jq '.'
+```
+
+Filter by date range using `from_date` and `to_date` (format: `YYYY-MM-DD`):
+
+```bash
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/get/{{< variable "PROJECT_ID" >}}?from_date=2025-01-01&to_date=2025-01-31&limit=50" \
+  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
+  -H "accept: application/json" | jq '.'
+```
+
+### Filter by recipient
+
+Retrieve events for one or more specific email addresses:
+
+```bash
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/email/{{< variable "PROJECT_ID" >}}?email=user@example.com&email=other@example.com" \
+  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
+  -H "accept: application/json" | jq '.'
+```
+
+### Filter by event type
+
+Retrieve events of a specific type.
+Supported values: `processed`, `delivered`, `bounce`, `deferred`, `dropped`, `spamreport`, `open`, `click`.
+
+```bash
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/bounce/{{< variable "PROJECT_ID" >}}" \
+  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
+  -H "accept: application/json" | jq '.'
+```
+
+## View delivery statistics
+
+Retrieve aggregated daily statistics for a project. Defaults to the last 30 days.
+
+```bash
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/stats/{{< variable "PROJECT_ID" >}}" \
+  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
+  -H "accept: application/json" | jq '.'
+```
+
+Use `start_date` and `end_date` to narrow the range:
+
+```bash
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/stats/{{< variable "PROJECT_ID" >}}?start_date=2025-01-01&end_date=2025-01-31" \
+  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
+  -H "accept: application/json" | jq '.'
+```
+
+## Manage suppression lists
+
+Suppression lists prevent sending to addresses that have bounced or blocked your emails.
+
+### Bounces
+
+List addresses that have hard-bounced:
+
+```bash
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/bouncelist/{{< variable "PROJECT_ID" >}}" \
+  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
+  -H "accept: application/json" | jq '.'
+```
+
+Remove an address from the bounce list only after confirming the address is valid:
+
+```bash
+curl -X DELETE "https://platform.sendgrid.pltfrm.sh/api/v1/self/bouncelist/{{< variable "PROJECT_ID" >}}" \
+  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
+  -H "content-type: application/json" \
+  -d '{"email": "user@example.com"}'
+```
+
+### Blocks
+
+List addresses that have blocked your emails or marked them as spam:
+
+```bash
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/blocklist/{{< variable "PROJECT_ID" >}}" \
+  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
+  -H "accept: application/json" | jq '.'
+```
+
+Remove an address from the block list to resume sending:
+
+```bash
+curl -X DELETE "https://platform.sendgrid.pltfrm.sh/api/v1/self/blocklist/{{< variable "PROJECT_ID" >}}" \
+  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
+  -H "content-type: application/json" \
+  -d '{"email": "user@example.com"}'
+```
+
+{{% note theme="warning" %}}
+
+Removing an address from a suppression list doesn't guarantee future delivery.
+If the underlying issue (invalid address, spam complaint) isn't resolved,
+the address is likely to be suppressed again.
+
+{{% /note %}}

From 3acf4a4aeed9b7f149ca73e32c6511c65a3359a8 Mon Sep 17 00:00:00 2001
From: C T <215163593+catplat@users.noreply.github.com>
Date: Mon, 6 Apr 2026 14:29:01 -0400
Subject: [PATCH 2/9] add date format clarification

---
 sites/platform/src/development/email-observability.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sites/platform/src/development/email-observability.md b/sites/platform/src/development/email-observability.md
index 67e510439b..0c6d77db5c 100644
--- a/sites/platform/src/development/email-observability.md
+++ b/sites/platform/src/development/email-observability.md
@@ -80,7 +80,7 @@ curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/stats/{{< variable "PROJEC
   -H "accept: application/json" | jq '.'
 ```
 
-Use `start_date` and `end_date` to narrow the range:
+Use `start_date` and `end_date` to narrow the range (format: `YYYY-MM-DD`):
 
 ```bash
 curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/stats/{{< variable "PROJECT_ID" >}}?start_date=2025-01-01&end_date=2025-01-31" \

From b761e709d1087e2f44ffce55e9012adf861a54ea Mon Sep 17 00:00:00 2001
From: C T <215163593+catplat@users.noreply.github.com>
Date: Wed, 22 Apr 2026 12:30:29 -0400
Subject: [PATCH 3/9] Update curl commands - needs review

---
 .../src/development/email-observability.md    | 22 ++++++++++---------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/sites/platform/src/development/email-observability.md b/sites/platform/src/development/email-observability.md
index 0c6d77db5c..f9e27c90c1 100644
--- a/sites/platform/src/development/email-observability.md
+++ b/sites/platform/src/development/email-observability.md
@@ -36,7 +36,7 @@ To get an access token:
 Retrieve a log of delivery events for a project:
 
 ```bash
-curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/get/{{< variable "PROJECT_ID" >}}" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -44,7 +44,7 @@ curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/get/{{< variable
 Filter by date range using `from_date` and `to_date` (format: `YYYY-MM-DD`):
 
 ```bash
-curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/get/{{< variable "PROJECT_ID" >}}?from_date=2025-01-01&to_date=2025-01-31&limit=50" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{< variable "PROJECT_ID" >}}?from_date=2025-01-01&to_date=2025-01-31&limit=50" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -54,7 +54,7 @@ curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/get/{{< variable
 Retrieve events for one or more specific email addresses:
 
 ```bash
-curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/email/{{< variable "PROJECT_ID" >}}?email=user@example.com&email=other@example.com" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/email/platformsh-auth/{{< variable "PROJECT_ID" >}}?email=user@example.com&email=other@example.com" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -64,8 +64,10 @@ curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/email/{{< variabl
 Retrieve events of a specific type.
 Supported values: `processed`, `delivered`, `bounce`, `deferred`, `dropped`, `spamreport`, `open`, `click`.
 
+Example `bounce` event type:
+
 ```bash
-curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/bounce/{{< variable "PROJECT_ID" >}}" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/bounce/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -75,7 +77,7 @@ curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/bounce/{{< variab
 Retrieve aggregated daily statistics for a project. Defaults to the last 30 days.
 
 ```bash
-curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/stats/{{< variable "PROJECT_ID" >}}" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -83,7 +85,7 @@ curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/stats/{{< variable "PROJEC
 Use `start_date` and `end_date` to narrow the range (format: `YYYY-MM-DD`):
 
 ```bash
-curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/stats/{{< variable "PROJECT_ID" >}}?start_date=2025-01-01&end_date=2025-01-31" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< variable "PROJECT_ID" >}}?start_date=2025-01-01&end_date=2025-01-31" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -97,7 +99,7 @@ Suppression lists prevent sending to addresses that have bounced or blocked your
 List addresses that have hard-bounced:
 
 ```bash
-curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/bouncelist/{{< variable "PROJECT_ID" >}}" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/bouncelist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -105,7 +107,7 @@ curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/bouncelist/{{< variable "P
 Remove an address from the bounce list only after confirming the address is valid:
 
 ```bash
-curl -X DELETE "https://platform.sendgrid.pltfrm.sh/api/v1/self/bouncelist/{{< variable "PROJECT_ID" >}}" \
+curl -X DELETE "https://sendgrid.pltfrm.sh/api/v1/sendgrid/bouncelist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "content-type: application/json" \
   -d '{"email": "user@example.com"}'
@@ -116,7 +118,7 @@ curl -X DELETE "https://platform.sendgrid.pltfrm.sh/api/v1/self/bouncelist/{{< v
 List addresses that have blocked your emails or marked them as spam:
 
 ```bash
-curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/blocklist/{{< variable "PROJECT_ID" >}}" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/blocklist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -124,7 +126,7 @@ curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/blocklist/{{< variable "PR
 Remove an address from the block list to resume sending:
 
 ```bash
-curl -X DELETE "https://platform.sendgrid.pltfrm.sh/api/v1/self/blocklist/{{< variable "PROJECT_ID" >}}" \
+curl -X DELETE "https://sendgrid.pltfrm.sh/api/v1/sendgrid/blocklist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "content-type: application/json" \
   -d '{"email": "user@example.com"}'

From daba1354c437bab1c61f4491af0b6cb3026f498c Mon Sep 17 00:00:00 2001
From: C T <215163593+catplat@users.noreply.github.com>
Date: Wed, 29 Apr 2026 17:49:06 -0400
Subject: [PATCH 4/9] Updates for parity with Flex topic

---
 .../src/development/email-observability.md    | 67 +++++++++++++++----
 1 file changed, 53 insertions(+), 14 deletions(-)

diff --git a/sites/platform/src/development/email-observability.md b/sites/platform/src/development/email-observability.md
index f9e27c90c1..d68e7e747f 100644
--- a/sites/platform/src/development/email-observability.md
+++ b/sites/platform/src/development/email-observability.md
@@ -33,7 +33,7 @@ To get an access token:
 
 ## Query message history
 
-Retrieve a log of delivery events for a project:
+Retrieve a log of email events for a project:
 
 ```bash
 curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
@@ -41,14 +41,23 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{
   -H "accept: application/json" | jq '.'
 ```
 
-Filter by date range using `from_date` and `to_date` (format: `YYYY-MM-DD`):
+Example filtering by a specific month:
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{< variable "PROJECT_ID" >}}?from_date=2025-01-01&to_date=2025-01-31&limit=50" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{< variable "PROJECT_ID" >}}?from_date=2026-03-01&to_date=2026-03-31&limit=50" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
 
+### Parameters
+
+| Parameter   | Default | Description |
+|-------------|---------|-------------|
+| `limit`     | `30`    | Number of records to return. |
+| `offset`    | `0`     | Number of records to skip for pagination. |
+| `from_date` | —       | Start date filter (`YYYY-MM-DD`). |
+| `to_date`   | —       | End date filter (`YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`). |
+
 ### Filter by recipient
 
 Retrieve events for one or more specific email addresses:
@@ -61,10 +70,9 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/email/platformsh-auth/
 
 ### Filter by event type
 
-Retrieve events of a specific type.
-Supported values: `processed`, `delivered`, `bounce`, `deferred`, `dropped`, `spamreport`, `open`, `click`.
+Retrieve events of a specific type by passing `event_type` as a path segment in the URL.
 
-Example `bounce` event type:
+Example filtering by `bounce` events:
 
 ```bash
 curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/bounce/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
@@ -72,9 +80,17 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/bounce/platformsh-auth
   -H "accept: application/json" | jq '.'
 ```
 
+#### Parameters
+
+| Parameter    | Description |
+|--------------|-------------|
+| `event_type` | One of `processed`, `delivered`, `bounce`, `deferred`, `dropped`, `spamreport`, `open`, `click`. |
+
+The `limit`, `offset`, `from_date`, and `to_date` parameters from the [previous section](#parameters) also apply.
+
 ## View delivery statistics
 
-Retrieve aggregated daily statistics for a project. Defaults to the last 30 days.
+Retrieve aggregated daily delivery statistics for a project. This endpoint provides high-level metrics compatible with common visualization tools.
 
 ```bash
 curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
@@ -82,29 +98,44 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< varia
   -H "accept: application/json" | jq '.'
 ```
 
-Use `start_date` and `end_date` to narrow the range (format: `YYYY-MM-DD`):
+Example narrowing the range to a specific month:
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< variable "PROJECT_ID" >}}?start_date=2025-01-01&end_date=2025-01-31" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< variable "PROJECT_ID" >}}?start_date=2026-03-01&end_date=2026-03-31" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
 
+### Parameters
+
+| Parameter    | Default     | Description |
+|--------------|-------------|-------------|
+| `start_date` | 30 days ago | Start of the date range (`YYYY-MM-DD`). |
+| `end_date`   | Today       | End of the date range (`YYYY-MM-DD`). |
+
 ## Manage suppression lists
 
 Suppression lists prevent sending to addresses that have bounced or blocked your emails.
 
 ### Bounces
 
-List addresses that have hard-bounced:
+The bouncelist contains addresses that have hard-bounced. The system automatically suppresses further sending attempts to these addresses.
+
+#### List bounced addresses
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/bouncelist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \/{{< variable "PROJECT_ID" >}}" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/bouncelist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
 
-Remove an address from the bounce list only after confirming the address is valid:
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `limit`   | `50`    | Number of records to return. |
+
+#### Remove from bouncelist
+
+Only remove an address after confirming it is now valid. Returns `204 No Content` on success.
 
 ```bash
 curl -X DELETE "https://sendgrid.pltfrm.sh/api/v1/sendgrid/bouncelist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
@@ -115,7 +146,9 @@ curl -X DELETE "https://sendgrid.pltfrm.sh/api/v1/sendgrid/bouncelist/platformsh
 
 ### Blocks
 
-List addresses that have blocked your emails or marked them as spam:
+The blocklist prevents sending to addresses that have previously blocked your emails or marked them as spam, protecting your sender reputation.
+
+#### List blocked addresses
 
 ```bash
 curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/blocklist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
@@ -123,7 +156,13 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/blocklist/platformsh-auth/{{< v
   -H "accept: application/json" | jq '.'
 ```
 
-Remove an address from the block list to resume sending:
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `limit`   | `50`    | Number of records to return. |
+
+#### Remove from blocklist
+
+Removes an address to resume sending. Returns `204 No Content` on success.
 
 ```bash
 curl -X DELETE "https://sendgrid.pltfrm.sh/api/v1/sendgrid/blocklist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \

From e319e19fca1304ae9c171da27d9371283adef750 Mon Sep 17 00:00:00 2001
From: C T <215163593+catplat@users.noreply.github.com>
Date: Wed, 29 Apr 2026 17:55:42 -0400
Subject: [PATCH 5/9] Replace dates with variables

---
 sites/platform/src/development/email-observability.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/sites/platform/src/development/email-observability.md b/sites/platform/src/development/email-observability.md
index d68e7e747f..9fe2f2c0be 100644
--- a/sites/platform/src/development/email-observability.md
+++ b/sites/platform/src/development/email-observability.md
@@ -44,7 +44,7 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{
 Example filtering by a specific month:
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{< variable "PROJECT_ID" >}}?from_date=2026-03-01&to_date=2026-03-31&limit=50" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{< variable "PROJECT_ID" >}}?from_date={{< variable "FROM_DATE" "YYYY-MM-DD" >}}&to_date={{< variable "TO_DATE" "YYYY-MM-DD" >}}&limit=50" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -101,7 +101,7 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< varia
 Example narrowing the range to a specific month:
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< variable "PROJECT_ID" >}}?start_date=2026-03-01&end_date=2026-03-31" \
+curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< variable "PROJECT_ID" >}}?start_date={{< variable "START_DATE" "YYYY-MM-DD" >}}&end_date={{< variable "END_DATE" "YYYY-MM-DD" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```

From fbbddab99ccc1a9594102f80dc04ccdef34fbbf9 Mon Sep 17 00:00:00 2001
From: C T <215163593+catplat@users.noreply.github.com>
Date: Mon, 4 May 2026 12:07:38 -0400
Subject: [PATCH 6/9] Fix misleading link: update with link to console and
 separate reference to docs topic.

---
 sites/platform/src/development/email-observability.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/sites/platform/src/development/email-observability.md b/sites/platform/src/development/email-observability.md
index 9fe2f2c0be..11039804fe 100644
--- a/sites/platform/src/development/email-observability.md
+++ b/sites/platform/src/development/email-observability.md
@@ -20,7 +20,8 @@ You can access data only for projects listed in your token's claims.
 
 To get an access token:
 
-1. [Create an API token](/administration/cli/api-tokens.md) in the {{% vendor/name %}} Console.
+1. In the [Console](https://console.upsun.com), create an API token. For details, refer to [Create an API token](/administration/cli/api-tokens.md#2-create-an-api-token) in the product docs.
+
 2. Exchange it for an access token (valid for 15 minutes):
 
    ```bash

From 3052786302e2b8582fe5667455231131c0c71d2b Mon Sep 17 00:00:00 2001
From: C T <215163593+catplat@users.noreply.github.com>
Date: Mon, 4 May 2026 12:17:57 -0400
Subject: [PATCH 7/9] disable vale

---
 sites/platform/src/development/email-observability.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/sites/platform/src/development/email-observability.md b/sites/platform/src/development/email-observability.md
index 11039804fe..9cd09d068b 100644
--- a/sites/platform/src/development/email-observability.md
+++ b/sites/platform/src/development/email-observability.md
@@ -120,8 +120,9 @@ Suppression lists prevent sending to addresses that have bounced or blocked your
 
 ### Bounces
 
-The bouncelist contains addresses that have hard-bounced. The system automatically suppresses further sending attempts to these addresses.
+The bounce list contains addresses that have hard-bounced. The system automatically suppresses further sending attempts to these addresses.
 
+<!-- vale of -->
 #### List bounced addresses
 
 ```bash
@@ -134,7 +135,7 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/bouncelist/platformsh-auth/{{<
 |-----------|---------|-------------|
 | `limit`   | `50`    | Number of records to return. |
 
-#### Remove from bouncelist
+#### Remove from bounce list
 
 Only remove an address after confirming it is now valid. Returns `204 No Content` on success.
 
@@ -144,7 +145,7 @@ curl -X DELETE "https://sendgrid.pltfrm.sh/api/v1/sendgrid/bouncelist/platformsh
   -H "content-type: application/json" \
   -d '{"email": "user@example.com"}'
 ```
-
+<!-- vale on -->
 ### Blocks
 
 The blocklist prevents sending to addresses that have previously blocked your emails or marked them as spam, protecting your sender reputation.

From 0cdc27bcf6d8dcf9c506d65fc8d46e1d2c750d4f Mon Sep 17 00:00:00 2001
From: C T <215163593+catplat@users.noreply.github.com>
Date: Mon, 4 May 2026 12:50:28 -0400
Subject: [PATCH 8/9] Revert to public API endpoints

---
 .../src/development/email-observability.md    | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/sites/platform/src/development/email-observability.md b/sites/platform/src/development/email-observability.md
index 9cd09d068b..fd7865c9a4 100644
--- a/sites/platform/src/development/email-observability.md
+++ b/sites/platform/src/development/email-observability.md
@@ -37,7 +37,7 @@ To get an access token:
 Retrieve a log of email events for a project:
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/get/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -45,7 +45,7 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{
 Example filtering by a specific month:
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{< variable "PROJECT_ID" >}}?from_date={{< variable "FROM_DATE" "YYYY-MM-DD" >}}&to_date={{< variable "TO_DATE" "YYYY-MM-DD" >}}&limit=50" \
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/get/{{< variable "PROJECT_ID" >}}?from_date={{< variable "FROM_DATE" "YYYY-MM-DD" >}}&to_date={{< variable "TO_DATE" "YYYY-MM-DD" >}}&limit=50" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -64,7 +64,7 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/get/platformsh-auth/{{
 Retrieve events for one or more specific email addresses:
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/email/platformsh-auth/{{< variable "PROJECT_ID" >}}?email=user@example.com&email=other@example.com" \
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/email/{{< variable "PROJECT_ID" >}}?email=user@example.com&email=other@example.com" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -76,7 +76,7 @@ Retrieve events of a specific type by passing `event_type` as a path segment in
 Example filtering by `bounce` events:
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/messages/bounce/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/bounce/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -94,7 +94,7 @@ The `limit`, `offset`, `from_date`, and `to_date` parameters from the [previous
 Retrieve aggregated daily delivery statistics for a project. This endpoint provides high-level metrics compatible with common visualization tools.
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/stats/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -102,7 +102,7 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< varia
 Example narrowing the range to a specific month:
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/stats/platformsh-auth/{{< variable "PROJECT_ID" >}}?start_date={{< variable "START_DATE" "YYYY-MM-DD" >}}&end_date={{< variable "END_DATE" "YYYY-MM-DD" >}}" \
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/stats/{{< variable "PROJECT_ID" >}}?start_date={{< variable "START_DATE" "YYYY-MM-DD" >}}&end_date={{< variable "END_DATE" "YYYY-MM-DD" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -126,7 +126,7 @@ The bounce list contains addresses that have hard-bounced. The system automatica
 #### List bounced addresses
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/bouncelist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/bouncelist/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -140,7 +140,7 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/bouncelist/platformsh-auth/{{<
 Only remove an address after confirming it is now valid. Returns `204 No Content` on success.
 
 ```bash
-curl -X DELETE "https://sendgrid.pltfrm.sh/api/v1/sendgrid/bouncelist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
+curl -X DELETE "https://platform.sendgrid.pltfrm.sh/api/v1/self/bouncelist/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "content-type: application/json" \
   -d '{"email": "user@example.com"}'
@@ -153,7 +153,7 @@ The blocklist prevents sending to addresses that have previously blocked your em
 #### List blocked addresses
 
 ```bash
-curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/blocklist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
+curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/blocklist/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "accept: application/json" | jq '.'
 ```
@@ -167,7 +167,7 @@ curl "https://sendgrid.pltfrm.sh/api/v1/sendgrid/blocklist/platformsh-auth/{{< v
 Removes an address to resume sending. Returns `204 No Content` on success.
 
 ```bash
-curl -X DELETE "https://sendgrid.pltfrm.sh/api/v1/sendgrid/blocklist/platformsh-auth/{{< variable "PROJECT_ID" >}}" \
+curl -X DELETE "platform.sendgrid.pltfrm.sh/api/v1/self/blocklist/{{< variable "PROJECT_ID" >}}" \
   -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
   -H "content-type: application/json" \
   -d '{"email": "user@example.com"}'

From 7e53515021a568297a64cc8c5104abff120488b7 Mon Sep 17 00:00:00 2001
From: C T <215163593+catplat@users.noreply.github.com>
Date: Thu, 14 May 2026 15:13:29 -0400
Subject: [PATCH 9/9] Remove Authentication section; add Before you begin; use
 recommended commands

---
 .../src/development/email-observability.md    | 62 +++++++------------
 1 file changed, 24 insertions(+), 38 deletions(-)

diff --git a/sites/platform/src/development/email-observability.md b/sites/platform/src/development/email-observability.md
index fd7865c9a4..6a06f27476 100644
--- a/sites/platform/src/development/email-observability.md
+++ b/sites/platform/src/development/email-observability.md
@@ -13,24 +13,10 @@ This API sits on top of the SendGrid infrastructure used by {{% vendor/name %}}'
 [built-in SMTP proxy](/development/email.md).
 It doesn't provide direct access to SendGrid — all data is scoped to the projects your token is authorized for.
 
-## Authentication
+## Before you begin
 
-All requests require a short-lived OAuth2 access token passed as a Bearer token.
-You can access data only for projects listed in your token's claims.
-
-To get an access token:
-
-1. In the [Console](https://console.upsun.com), create an API token. For details, refer to [Create an API token](/administration/cli/api-tokens.md#2-create-an-api-token) in the product docs.
-
-2. Exchange it for an access token (valid for 15 minutes):
-
-   ```bash
-   curl -u platform-api-user: \
-     -d 'grant_type=api_token&api_token={{< variable "API_TOKEN" >}}' \
-     https://auth.api.platform.sh/oauth2/token
-   ```
-
-   Use the `access_token` value from the response as the Bearer token in your requests.
+- Authenticate the {{% vendor/name %}} CLI to your account by running `{{% vendor/cli %}} login` or `{{% vendor/cli %}}`.
+- Find your project ID, used in place of `{{< variable "PROJECT_ID" >}}` in the commands below. To find it, run `{{% vendor/cli %}} project:info id`.
 
 ## Query message history
 
@@ -38,16 +24,16 @@ Retrieve a log of email events for a project:
 
 ```bash
 curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/get/{{< variable "PROJECT_ID" >}}" \
-  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
-  -H "accept: application/json" | jq '.'
+  -H "$({{% vendor/cli %}} auth:token -WH)" \
+  -H "accept: application/json" -s | jq '.'
 ```
 
 Example filtering by a specific month:
 
 ```bash
 curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/get/{{< variable "PROJECT_ID" >}}?from_date={{< variable "FROM_DATE" "YYYY-MM-DD" >}}&to_date={{< variable "TO_DATE" "YYYY-MM-DD" >}}&limit=50" \
-  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
-  -H "accept: application/json" | jq '.'
+  -H "$({{% vendor/cli %}} auth:token -WH)" \
+  -H "accept: application/json" -s | jq '.'
 ```
 
 ### Parameters
@@ -65,8 +51,8 @@ Retrieve events for one or more specific email addresses:
 
 ```bash
 curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/email/{{< variable "PROJECT_ID" >}}?email=user@example.com&email=other@example.com" \
-  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
-  -H "accept: application/json" | jq '.'
+  -H "$({{% vendor/cli %}} auth:token -WH)" \
+  -H "accept: application/json" -s | jq '.'
 ```
 
 ### Filter by event type
@@ -77,8 +63,8 @@ Example filtering by `bounce` events:
 
 ```bash
 curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/messages/bounce/{{< variable "PROJECT_ID" >}}" \
-  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
-  -H "accept: application/json" | jq '.'
+  -H "$({{% vendor/cli %}} auth:token -WH)" \
+  -H "accept: application/json" -s | jq '.'
 ```
 
 #### Parameters
@@ -95,16 +81,16 @@ Retrieve aggregated daily delivery statistics for a project. This endpoint provi
 
 ```bash
 curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/stats/{{< variable "PROJECT_ID" >}}" \
-  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
-  -H "accept: application/json" | jq '.'
+  -H "$({{% vendor/cli %}} auth:token -WH)" \
+  -H "accept: application/json" -s | jq '.'
 ```
 
 Example narrowing the range to a specific month:
 
 ```bash
 curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/stats/{{< variable "PROJECT_ID" >}}?start_date={{< variable "START_DATE" "YYYY-MM-DD" >}}&end_date={{< variable "END_DATE" "YYYY-MM-DD" >}}" \
-  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
-  -H "accept: application/json" | jq '.'
+  -H "$({{% vendor/cli %}} auth:token -WH)" \
+  -H "accept: application/json" -s | jq '.'
 ```
 
 ### Parameters
@@ -122,13 +108,13 @@ Suppression lists prevent sending to addresses that have bounced or blocked your
 
 The bounce list contains addresses that have hard-bounced. The system automatically suppresses further sending attempts to these addresses.
 
-<!-- vale of -->
+<!-- vale off -->
 #### List bounced addresses
 
 ```bash
 curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/bouncelist/{{< variable "PROJECT_ID" >}}" \
-  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
-  -H "accept: application/json" | jq '.'
+  -H "$({{% vendor/cli %}} auth:token -WH)" \
+  -H "accept: application/json" -s | jq '.'
 ```
 
 | Parameter | Default | Description |
@@ -141,8 +127,8 @@ Only remove an address after confirming it is now valid. Returns `204 No Content
 
 ```bash
 curl -X DELETE "https://platform.sendgrid.pltfrm.sh/api/v1/self/bouncelist/{{< variable "PROJECT_ID" >}}" \
-  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
-  -H "content-type: application/json" \
+  -H "$({{% vendor/cli %}} auth:token -WH)" \
+  -H "accept: application/json" -s | jq '.' \
   -d '{"email": "user@example.com"}'
 ```
 <!-- vale on -->
@@ -154,8 +140,8 @@ The blocklist prevents sending to addresses that have previously blocked your em
 
 ```bash
 curl "https://platform.sendgrid.pltfrm.sh/api/v1/self/blocklist/{{< variable "PROJECT_ID" >}}" \
-  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
-  -H "accept: application/json" | jq '.'
+  -H "$({{% vendor/cli %}} auth:token -WH)" \
+  -H "accept: application/json" -s | jq '.'
 ```
 
 | Parameter | Default | Description |
@@ -168,8 +154,8 @@ Removes an address to resume sending. Returns `204 No Content` on success.
 
 ```bash
 curl -X DELETE "platform.sendgrid.pltfrm.sh/api/v1/self/blocklist/{{< variable "PROJECT_ID" >}}" \
-  -H "Authorization: Bearer {{< variable "ACCESS_TOKEN" >}}" \
-  -H "content-type: application/json" \
+  -H "$({{% vendor/cli %}} auth:token -WH)" \
+  -H "accept: application/json" -s | jq '.' \
   -d '{"email": "user@example.com"}'
 ```