Notifications API
5 endpoints in this group.
POST /api/notifications
Create Notification Endpoint
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | required |
Request body: application/json
Responses
| Code | Description |
|---|---|
202 | Successful Response |
422 | Validation Error |
GET /api/notifications/suppressions
List Suppressions Endpoint
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channel | query | — | optional | |
recipient | query | — | optional | |
limit | query | integer | optional |
Responses
| Code | Description |
|---|---|
200 | Successful Response |
422 | Validation Error |
DELETE /api/notifications/suppressions/{suppression_id}
Delete Suppression Endpoint
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
suppression_id | path | integer | required |
Responses
| Code | Description |
|---|---|
204 | Successful Response |
422 | Validation Error |
GET /api/notifications/unsubscribe
One Click Unsubscribe Get
Read-only confirmation endpoint. Does not execute the unsubscribe.
Returns a 200 with next_action='post_to_confirm' so a frontend
confirmation page can fetch this to render context, then submit a
POST when the user clicks confirm. Mail-client link-prefetchers
hitting this URL with GET do nothing destructive.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
token | query | string | required |
Responses
| Code | Description |
|---|---|
200 | Successful Response |
422 | Validation Error |
POST /api/notifications/unsubscribe
One Click Unsubscribe Post
RFC 8058 one-click unsubscribe. POST is the executing path —
mail clients sending the List-Unsubscribe-Post: List-Unsubscribe=One-Click header will POST to this URL.
There is intentionally NO GET endpoint that mutates state. Email link-prefetchers and image-scanning antivirus that GET URLs would otherwise silently unsubscribe legitimate recipients (CSRF-adjacent via mail-client auto-fetch). The frontend confirmation page (when one exists) lives outside this API.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
token | query | string | required |
Responses
| Code | Description |
|---|---|
200 | Successful Response |
422 | Validation Error |