/v1/workspaces/{workspace_id}/recipients/{external_id}/preference-linkAuthCreate 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 · uuidId of the workspace.
external_id*stringYour user id for the recipient (URL-encoded): 1-255 of `A-Z a-z 0-9 . _ : @ | -`.
Request body
category_keystringA 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 · uriThe 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-timeWhen the link stops working (365 days after it was made). Make a new one per email; old ones keep working until then.
category_key*stringThe 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"
}