Unsubscribe (RFC 8058 one-click)

POST /v1/public/email/unsubscribe

• Operation ID: unsubscribeEmailOneClick
• Tags: Email unsubscribe
• Base URL: http://localhost:8787

Target of the List-Unsubscribe-Post header: mail clients POST List-Unsubscribe=One-Click to the same URL, with the token in the query string. The request body is not read. Records an unsubscribe with reason one-click.

Workflow: Integration guide.

Authentication: none (public).

Rate limit: 30 requests per 60s per ip.

Authentication

• Auth: none (public endpoint, no token required).

Rate limit

30 requests per 60 seconds per ip. Exceeding it returns 429.

Parameters

Name	In	Type	Required	Description
token	query	string	yes	Min length: 10. Max length: 2000

Responses

200

Unsubscribed.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object

Field	Type	Required	Description
ok	boolean	yes	One of: true

Errors

400

Request validation failed. validation_failed with details.token = "invalid": the token is malformed, tampered or expired.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ValidationErrorBody) | object (ErrorBody)

Field	Type	Required	Description
(variant 1).success	boolean	yes	One of: false
(variant 1).error	object	yes	-
(variant 1).error.name	string	yes	One of: "ZodError"
(variant 1).error.issues	object[]	yes	-
(variant 1).error.issues[].code	string	yes	-
(variant 1).error.issues[].path	(string | number)[]	yes	-
(variant 1).error.issues[].message	string	yes	-
(variant 2).error	string	yes	Stable machine-readable error code, e.g. forbidden, not_found.
(variant 2).details	any	no	Optional structured context. For 403 it is { perm }.

Request validation

{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "custom",
        "path": [
          "field"
        ],
        "message": "Invalid value"
      }
    ]
  }
}

Application error

{
  "error": "validation_failed"
}

429

Rate limit exceeded (rate_limited).

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody)

Field	Type	Required	Description
error	string	yes	Stable machine-readable error code, e.g. forbidden, not_found.
details	any	no	Optional structured context. For 403 it is { perm }.

Error response

{
  "error": "rate_limited"
}

500

Unexpected server error (internal). No details are returned.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "internal"
}

503

Maintenance can refuse this write before authentication (degraded blocks session start and checkout; lockdown blocks other public/user writes).

• Header x-request-id: Request identifier; quote it when reporting an error.
• Header Retry-After: Maintenance retry delay in seconds; present for panic_mode. Example: 30. Content type: application/json

Schema: object (MaintenanceErrorBody)

Field	Type	Required	Description
error	string	yes	One of: "panic_mode"
level	string	yes	One of: "degraded", "lockdown"
reason	string | null	yes	-

Maintenance lockdown

{
  "error": "panic_mode",
  "level": "lockdown",
  "reason": "Scheduled maintenance"
}

Examples

curl

curl -X POST 'http://localhost:8787/v1/public/email/unsubscribe?token=example000'

TypeScript

const response = await fetch("http://localhost:8787/v1/public/email/unsubscribe?token=example000", {
  method: "POST",
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = response.status === 204 || response.status === 205
  ? undefined
  : response.headers.get("content-type")?.includes("json")
    ? await response.json()
    : await response.text();