Unsubscribe via link

GET /v1/public/email/unsubscribe

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

Opened from the unsubscribe link in broadcast emails. The signed token is the credential; no Authorization header. Records an unsubscribe with reason link for the token's address and returns an HTML confirmation page. Account and security email is unaffected.

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

HTML confirmation page.

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

Schema: string

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"
}

Examples

curl

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

TypeScript

const response = await fetch("http://localhost:8787/v1/public/email/unsubscribe?token=example000", {
  method: "GET",
});
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();