Skip to content

ADR-0012: Single path for sending messages, with consent

  • Status: Accepted
  • Date: 2026-11-13

Messages to candidates start in many places: the inbox, the candidate record, automation rules, sequences, broadcasts, interview reminders and the first contact after an application. Texting people in the United States depends on recorded consent, on honouring a request to stop and on sending hours. Those rules must hold whichever feature sends.

Where are the rules of an outgoing message applied?

  • Consent and opt-out are checked once, in one place, for every origin.
  • No feature and no user can skip a refusal.
  • Every message, sent or refused, is recorded with its reason.
  • The same message is never sent twice.
  1. One sending service that every feature must call, and that is the only code allowed to queue a message.
  2. Each feature calls the provider and applies shared checks. Obvious alternative, rejected by rule: no screen, route or routine calls a provider on its own.

Chosen option: 1.

MessageSendService, in apps/api/src/modules/platform-messaging, is the public door. In one transaction it claims the idempotency key, locks the conversation, renders the text in the language of the candidate and then checks, in this order: archived candidate; destination; consent or suppression; sender; daily cap; a variable of the text without a value; the unsubscribe page of an automatic email. The first check that fails is the reason of the refusal. A message that passes is written in messages as queued, or as scheduled when it is automatic and outside the allowed window. It never calls a provider: the worker sends what is queued (ADR-0006). A refusal is also a row, created as canceled with its reason, and there is no option to override it.

The rules it applies:

  • An SMS needs the recorded consent of the candidate, including a message typed by a recruiter, and goes only to the primary phone of the record.
  • Automatic messages (automation, sequence, broadcast, reminder) leave only inside the sending window of the company, which cannot be wider than 8:00 to 21:00 in the time zone of the candidate. Outside it they wait for the window to open. A message typed by a user leaves at once. The first SMS after an application follows the window unless the company turns on “Send the first message at any hour”.
  • SMS from automations, sequences and broadcasts are capped per candidate per day (3 by default). What exceeds the cap is discarded and recorded, not postponed.
  • Email is not sent to an address that unsubscribed, bounced or complained.

The only message exempt from consent is the confirmation reply to STOP, START and HELP, written by a service private to the module. Incoming messages have one path too: a STOP keyword withdraws the consent in the same transaction that records the message and cancels what was pending for that candidate.

  • Good, because a new sending feature inherits every rule by construction.
  • Good, because the timeline of the candidate shows refused messages with the reason, so a user sees why nothing was sent.
  • Good, because the idempotency key makes a retry safe.
  • Bad, because there is no override, not even for an administrator of the company. A recruiter cannot text a candidate who has no recorded consent.
  • Bad, because every sending feature depends on one module, so a change of its interface reaches all of them.
  • Bad, because sending is asynchronous: the user sees the message as queued before it is delivered.
  • apps/api/src/modules/platform-messaging/message-send.service.ts and message-send.types.ts: the service, its input and the refusal reasons.
  • apps/api/src/modules/platform-messaging/inbound-message.service.ts and keyword-reply.service.ts: the receiving path and the keyword replies.
  • packages/db/src/schema/messaging.ts: messaging_settings, with the window and the cap of each company.
  • Concept page: Messaging.
  • User guide: Messaging settings, Limits.
  • Related: ADR-0013, ADR-0019 for the status of the sending hours and keyword texts.