Skip to content
EdgeKit

Confirm a pending newsletter subscription

POST
/v1/newsletters/confirm
curl --request POST \
  --url https://your-tenant-host/v1/newsletters/confirm \
  --header 'Content-Type: application/json' \
  --data '{ "token": "example" }'

Flips pending → subscribed for the one list the token names, and does nothing on any other state. One-time use comes from the subscription state, never from the token: a replayed link finds nothing pending and answers confirmed: false at 200, the same as a first click that already worked. The site comes from the verified token and nowhere else, because an emailed link carries no x-edgekit-site-id header. Safe to retry, for the same reason.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
token
required

The signed token from the confirmation link, carrying (userId, listId, siteId, exp). One-time use comes from the subscription state, not from the token: confirming flips pending → subscribed, so a replayed link finds nothing pending and does nothing.

string
>= 1 characters

Example generated

{
  "token": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The list, and whether this request is what moved it.

Media typeapplication/json
object
confirmed
required

Whether this request is what confirmed the subscription. false for a replay, and still a 200.

boolean
list
required
object
id
required

The list’s id (UUIDv7). A list is named by its id, never by its slug.

string format: uuid
slug
required

^[a-z][a-z0-9_]*$, unique per site: two sites in one organization can both run a morning_briefing, so it is not unique per tenant.

string
label
required

What a preference centre renders and what the confirmation email says it is confirming. Tenant-authored, staged and deployed.

string
description
required

A sentence, or null. Shown in the confirmation email beside the label; without it, somebody subscribing to two lists gets two identical emails.

string | null

Example 

{
  "list": {
    "id": "01999b1e-7a40-7c2d-9e51-2a4c8d0f6b31",
    "slug": "morning_briefing",
    "label": "The Morning Briefing"
  }
}

400

Section titled “400”

Invalid request.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Example 

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

404

Section titled “404”

Resource not found.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Example 

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

422

Section titled “422”

Request validation failed.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Example 

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

500

Section titled “500”

Unexpected error.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Example 

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

503

Section titled “503”

With Retry-After, briefly unavailable; without it, not configured.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Example 

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}