Notify API reference

Notify API · Recipients

post/v1/workspaces/{workspace_id}/recipients/{external_id}/preference-linkAuth

Create a hosted preference page link

Returns a signed link to a page, hosted by Notify in your workspace's branding (`branding` in settings), where this recipient switches each category on or off per channel, sets quiet hours and a time zone, or unsubscribes from everything except critical types. It needs no sign-in, so it works from any email, also for people who never open your app. The link is valid for 365 days. Changes are recorded in the recipient's consent history with source `hosted_page`. Each call returns a fresh link and changes nothing, so it takes no `Idempotency-Key`.

Path parameters

workspace_id*string · uuid

Id of the workspace.

external_id*string

Your user id for the recipient (URL-encoded): 1-255 of `A-Z a-z 0-9 . _ : @ | -`.

Request body

category_keystring

A category key. The page then opens with a one-click "Unsubscribe from these emails" for that category, the way the `List-Unsubscribe` header of a Notify email does. Leave it out for a general link (an account settings page, a footer you write yourself).

Example: "product-updates"

Response · 201 The link.

url*string · uri

The hosted preference page for this recipient. Anyone holding it can change this recipient's preferences (never critical types), so send it only to the recipient, for example in an email footer. Opening it changes nothing; the page saves only when the person presses a button.

Example: "https://api.notify.productcraft.co/v1/preferences/p1.AQ…"

expires_at*string · date-time

When the link stops working (365 days after it was made). Make a new one per email; old ones keep working until then.

category_key*string

The category the link offers one-click unsubscribe from, if any.

Example

Request

POST https://api.notify.productcraft.co/v1/workspaces/{workspace_id}/recipients/{external_id}/preference-link
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "category_key": "product-updates"
}

Response

{
  "url": "https://api.notify.productcraft.co/v1/preferences/p1.AQ…",
  "expires_at": "2026-01-01T00:00:00.000Z",
  "category_key": "string"
}