Email preferences namespace

Reference for reading and changing a person's email preferences from the link in the board's emails.

Use 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.

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 emailPreferences route 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-Token header, 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:

FieldTypeBehavior
object'email_preferences'Resource discriminator.
emailstringThe address the preferences are for.
jobAlertsobjectconfirmed, 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.
jobMatchesobject | nullsubscribed and waitlisted for weekly job matches. null when the board sends this person none; hide the switch.
marketingobjectsubscribed: the person gets the board's marketing email.
topicsarrayEvery 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.

FieldBehavior
alertsUp 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.
jobAlertsTurns 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.
jobMatchesTurns weekly job matches on or off. On rejects with candidate_notification_preference_paused (422) where the board sends this person none.
marketingTurns 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).
consentTextRequired 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.
sourceOptional label for the page, such as email-preferences, kept with the consent.
pageUrlOptional 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.