Email preferences namespace
Reference for reading and changing a person's email preferences from the link in the board's emails.
A
JUse board.emailPreferences to build the page every email from the board links to. One page covers the person's job alerts, job matches, the board's marketing email and each marketing topic, and it can unsubscribe them from all of it at once.
The preferences link
Emails from the board link to its email preferences page with a token query parameter. The token names the person on this board, so the page needs no sign-in.
- Declare the page as the
emailPreferencesroute role (canonical path/email-preferences) so the board's emails link to it. A board that does not declare it gets a page Cavuno hosts. - Read the token from the page URL and pass it to each method. The SDK sends it in the
X-Email-Preferences-Tokenheader, never in an API URL. - A token from another board, or one that was changed, rejects with
email_preferences_token_invalid(403). Show that the link is not valid.
Shared behavior
Every method returns the Board API wire body unchanged and throws BoardApiError for a non-2xx response. The trailing FetchOptions passes abort signals, headers, and framework cache directives through to fetch. The methods work on every plan and behind a board password, so an opt-out always works.
board.emailPreferences.get
Returns the person's preferences. Reading changes nothing, so a mail scanner that opens the link does no harm.
EmailPreferences contains:
| Field | Type | Behavior |
|---|---|---|
object | 'email_preferences' | Resource discriminator. |
email | string | The address the preferences are for. |
jobAlerts | object | confirmed, unsubscribed (every alert turned off), waitlisted (on, waiting for room on the board's plan), and alerts: each alert's id, label, frequency, isActive (sending now), paused (paused by itself; it keeps its filters), awaitingConfirmation (not sending until the person clicks a confirmation link for it; still true while job alerts are off, and such an alert can't be paused), kind, anchorJob and filters. |
jobMatches | object | null | subscribed and waitlisted for weekly job matches. null when the board sends this person none; hide the switch. |
marketing | object | subscribed: the person gets the board's marketing email. |
topics | array | Every live marketing topic: key, name and subscribed. Topics narrow marketing, so show them as off while marketing is off. |
board.emailPreferences.update
Applies the changes together, as the person, and returns the preferences after them, plus confirmationEmailQueued: true when the change emailed a fresh confirmation link (job alerts back on with alerts waiting for one). Say "check your inbox" only when it is true.
| Field | Behavior |
|---|---|
alerts | Up to 10 changes by alert id: { id, paused } pauses or resumes the alert (one waiting for its confirmation link isn't paused), { id, delete: true } deletes it, { id, frequency } sets how often its digest is sent. Resuming one that waits for its confirmation link, or while the person waits for room, leaves it waiting. |
jobAlerts | Turns every job alert off or back on, as the Unsubscribe button a digest's link opens does. Back on restores the alerts that were on before, not ones paused by themselves. Alerts still waiting for a confirmation link, such as every alert of an address that never confirmed, get a fresh link by email; nothing changes and it rejects with rate_limited (429) within two minutes of the last one, or job_alert_email_suppressed (409) for an address that can't receive email. Applied after alerts. |
jobMatches | Turns weekly job matches on or off. On rejects with candidate_notification_preference_paused (422) where the board sends this person none. |
marketing | Turns the board's marketing email on or off. Topics that went off with marketing come back when it is turned on again. |
topics | { key, subscribed } per topic. Turning one on needs marketing on, in this change or already, or rejects with email_preferences_marketing_required (409). |
consentText | Required when turning marketing or a topic on: the wording shown next to the switch. It must name the board, and is kept with the person's consent. |
source | Optional label for the page, such as email-preferences, kept with the consent. |
pageUrl | Optional page URL, kept with the consent. Defaults to the request's Referer. |
Send only what the person changed, such as the one switch they flipped, not every topic on the page. A topic sent as subscribed: false is kept as the person's own choice: it stays off when marketing comes back on, and when a sign-up later adds new sign-ups to it.
Turning marketing or a topic on is the person's own opt-in. It is confirmed at once, because the token shows the link reached their inbox.
board.emailPreferences.unsubscribeAll
Turns off everything at once: job alerts, job matches, marketing and every topic. Only what the person has is changed, so calling it again changes nothing. The address can still sign up again later.