Job alerts

Build double-opt-in email alerts and signed-in alert management without mixing token models.

Cavuno supports two alert experiences. Anonymous email alerts use confirmation and HMAC manage tokens; signed-in candidates manage alerts under board.me.alerts. These tokens are not board-user sessions.

Prerequisites

board.context().features.jobAlerts is true.
A consent checkbox that is not preselected.
Routes for the confirmation and email-management links Cavuno sends.
A server-owned candidate session for board.me.alerts.

1// src/data/job-alerts.ts
2import { board } from '../lib/board';
3
4export async function subscribeToRemoteEngineering(email: string) {
5  return board.jobAlerts.subscribe({
6    email,
7    consent: true,
8    frequency: 'weekly',
9    filters: {
10      jobFunctions: ['engineering'],
11      remoteOptions: ['remote'],
12    },
13    context: { source: 'jobs-search' },
14  });
15}
16
17export function confirmJobAlert(token: string) {
18  return board.jobAlerts.confirm({ token });
19}

The subscription result always reports status: 'submitted' — a uniform response that never reveals whether the email was new or already subscribed (so it can't enumerate subscribers). A confirmation email is sent when the email isn't already subscribed. Confirmation itself always returns HTTP 200; branch on its status, which can be confirmed, already_confirmed, expired, or not_found.

Build the email management page

1export async function loadAlertManagement(
2  subscription: string,
3  token: string,
4) {
5  return board.jobAlerts.manage({ subscription, token });
6}
7
8export async function updateAlertPreference(input: {
9  subscriptionId: string;
10  preferenceId: string;
11  token: string;
12  frequency: 'weekly';
13}) {
14  return board.jobAlerts.updatePreference({
15    ...input,
16    filters: { remoteOptions: ['remote'] },
17  });
18}

Preference updates are full replacements. Restate frequency and every filter the subscriber wants to keep.

Weekly is the only supported alert cadence.

Build signed-in alerts

1const options = {
2  cache: 'no-store' as const,
3  headers: { authorization: `Bearer ${accessToken}` },
4};
5
6const alert = await board.me.alerts.create(
7  {
8    label: 'Remote engineering',
9    frequency: 'weekly',
10    jobFunctions: ['engineering'],
11    remoteOptions: ['remote'],
12  },
13  options,
14);

Use the returned alert.id for retrieve, update, and remove calls.

Expected result

Anonymous subscribe and resend calls always return a uniform status: 'submitted'; confirmation returns an explicit status for every normal branch. Signed-in creation returns an active alert that appears in board.me.alerts.list().

Verify the result

The subscription form is absent when job alerts are disabled.
New subscriptions cannot be created without explicit consent.
Expired and unknown confirmation tokens get distinct messages.
Anonymous manage URLs work without a board-user session.
Signed-in alert responses never enter a shared cache.

Errors and edge cases

Only job functions, place slugs, and remote options currently filter digest delivery. Seniority and salary values are stored but do not filter delivery.
Resend always returns status: 'submitted' — uniform regardless of subscription/confirmation/throttle state (the per-subscription and per-IP throttle still applies server-side).
Manage tokens grant access to one subscription. Treat them as secrets and keep them out of analytics and logs.
Do not exchange a manage token for a candidate session.

Production cautions

Explain cadence and consent next to the subscription control.
Use generic completion copy where revealing subscription existence would leak personal data.
Preserve the complete current preference on replacement updates.
Handle throttling without repeatedly calling resend.

Next, add signed-in communication with Messaging.