Skip to content

Messaging

This page describes the rules that decide whether a message to a candidate may leave, and where the code enforces them. It is part of section 9 of the arc42 template. The decisions are in ADR-0012 and ADR-0013, and the sequence from the route to the provider is drawn in Runtime view.

The consent texts, the keyword lists and the allowed hours described here are a regulatory preview: they implement the rules as the product team read them, and nothing on this page states that they satisfy a law. See ADR-0019.

Messages to candidates are sent by many features: a recruiter typing in the Inbox, automations, sequences, broadcasts, reminders and system notices. Text messages to a phone are regulated, and a mistake is made thousands of times once it is automated: texting a person who never agreed, texting again after STOP, texting at 6 in the morning, or sending the same text twice after a retry.

If each feature applied these rules on its own, each new feature would be a new chance to get one wrong.

  1. One path. Every outbound SMS and email is written by one service. No module calls a provider.
  2. Consent. An SMS leaves only to a candidate with recorded SMS consent, on the primary phone of the record. This includes a message typed by a recruiter.
  3. STOP. A request to stop withdraws the consent at once and cancels what was waiting for that person.
  4. Allowed window. An automatic message leaves only inside the sending window of the company, in the time zone of the candidate.
  5. Daily cap. Automatic SMS to one candidate are capped per day. What exceeds the cap is discarded, not delayed.
  6. Suppression. No email goes to an address that unsubscribed, bounced or complained.
  7. No override. A refusal is stored with its reason, and no caller, role or setting can skip it.

MessageSendService (apps/api/src/modules/platform-messaging/message-send.service.ts) is the only way a module sends. It has two methods, send and sendInTransaction, and both end in a private writer that:

  • decides whether the message may leave;
  • writes one row of messages, which is also the item of the candidate timeline;
  • never calls a provider. The worker sends what is queued.

Every call names its origin: manual, automation, sequence, broadcast, reminder or system. The origin decides which rules apply.

Rule manual automation, sequence, broadcast reminder system
Consent for SMS, suppression for email Yes Yes Yes Yes
Allowed window No, leaves at once Yes Yes No, leaves at once
Daily cap of SMS No Yes No No
Unsubscribe footer in email No Yes No No

Every call also carries an idempotency key, unique per company. The key is claimed first, in a table of its own. A second call with the same key writes nothing and returns the first message, so a retried job or a double click cannot send twice.

The checks run in one transaction and in a fixed order. The first one that fails is the reason stored in messages.status_reason.

%%{init: {"flowchart": {"wrappingWidth": 260}}}%%
flowchart TB
  key["<b>Idempotency key</b><br/>Claimed, or already used"]
  dup(["Return the first message.<br/>Nothing is written"])
  subgraph checks["Checks, in this order"]
    direction TB
    c1["1. The candidate is not archived"]
    c2["2. A destination is on record,<br/>and it is the primary one"]
    c3["3. SMS: consent on record.<br/>Email: address not suppressed"]
    c4["4. The sender is ready"]
    c5["5. Under the cap"]
    c6["6. Every variable has a value"]
    c7["7. Automatic email: an unsubscribe<br/>page is available"]
    c1 --> c2
    c2 --> c3
    c3 --> c4
    c4 --> c5
    c5 --> c6
    c6 --> c7
  end
  win["<b>Allowed window</b><br/>Automatic origins only"]
  canceled(["Stored as <b>canceled</b>,<br/>with the reason"])
  queued(["Stored as <b>queued</b>"])
  scheduled(["Stored as <b>scheduled</b>,<br/>for the window opening"])

  key -->|"Claimed"| c1
  key -.->|"Already used"| dup
  checks -.->|"First check<br/>that fails"| canceled
  c7 -->|"All passed"| win
  win -->|"Inside, or<br/>not automatic"| queued
  win -->|"Outside"| scheduled

Legend. Box: a step. Large box: the checks, which run top to bottom in the order of the code. Rounded box: how the call ends, with the status the row of messages is stored with. Dotted arrow: the path of a repeated key or of a refusal. A check that does not apply to the channel or the origin passes.

Check Reason stored on refusal
The candidate is archived candidate_archived
The record has no phone or email, or the caller named an address that is not the primary one no_destination, unverified_destination
SMS: the candidate never gave consent, or asked to stop no_consent, opted_out
Email: the address is suppressed suppressed
SMS: the company has no approved number with the provider in use. Email: the provider needs a reply address and the company has none sender_not_approved, no_reply_address
Automatic SMS: the daily cap of the candidate is reached daily_cap
The text uses a variable that has no value template_variable_missing
Automatic email: the company has no careers page address to host the unsubscribe link careers_address_required

A refused message is a row too, stored as canceled, so the timeline of the candidate shows that nothing was sent and why. The conversation row is locked during the checks, which puts two sends to the same candidate in series: two automations firing together cannot both pass under the cap.

Consent is a ledger, not a checkbox. candidate_consents is insert-only: each row says the channel, whether consent was granted or withdrawn, the text the person accepted, with its version and language when it came from the catalog, how it was captured (web_form, api, import, manual, sms_keyword or sms_provider) and when. The texts shown on the public forms come from consent_texts, a catalog of the platform where a new wording is a new version and an old one is never edited.

The current answer for SMS is the most recent row of the channel. A trigger of the database, gate.candidate_consents_sync, copies it to candidates.consent_sms, and the application role cannot write that column: the only way to change the consent of a candidate is to add a row to the ledger.

InboundMessageService (inbound-message.service.ts) is the one path a received message enters through. When the whole text of an SMS is a keyword, it is a request and not a message: “please stop calling me” stops nothing, while STOP, stop. and "Stop!" do.

For a stop keyword, one transaction:

  1. records the received message;
  2. adds the withdrawal to candidate_consents, dated after every other row of the channel, so a consent being written at the same moment by another path cannot win;
  3. cancels the pending messages of that SMS conversation;
  4. emits the event consent.revoked, which takes the candidate out of every sequence;
  5. queues the confirmation.

The confirmation is the only message that leaves without consent. It is written by KeywordReplyService, private to the messaging module: the public service refuses the idempotency key prefix reserved for it, the text is the system text in force for that keyword, and one received message is answered once. A start keyword gives the consent back the same way, and a help keyword answers with the company name and its contact. A phone number that belongs to no candidate gets at most one confirmation in 24 hours.

A stop that the SMS provider handled by itself, without the webhook reaching the system, is caught too: when the provider refuses a message because the phone opted out, the adapter records the withdrawal in the ledger.

The company sets the window in Platform > Integrations, on the Messaging tab. The database does not accept a window wider than 8:00 to 21:00 (messaging_settings_send_window_check).

The window is evaluated in the time zone of the candidate (time-zone.ts): from the state of the record; without a state, from the area code of the phone; without both, from the time zone of the company. A state that spans two time zones counts as both, and a message leaves only when it is inside the window in both.

An automatic message outside the window is not refused. It is stored as scheduled with the instant the window opens. Two exceptions exist: a message typed by a person and a system notice leave at once, and the first SMS after an application ignores the window only when the company turned on “Send the first message at any hour”.

Limit Value Source
Automatic SMS per candidate per day 3 by default; a company chooses 1 to 5 messaging_settings.auto_sms_daily_cap
Emails to an address that is not a candidate yet (the reminder of an abandoned application) 2 in 7 days ADDRESS_EMAIL_CAP in message-send.service.ts
Segments of one SMS 20 SMS_MAX_SEGMENTS in packages/contracts/src/sms-segments.ts
SMS a company sends per second 1 by default, set per company number messaging_settings.sms_rate_per_second
Emails a company sends per pass of the queue 20 EMAIL_BATCH_SIZE in send-queue.runner.ts

The day of the cap is the local day of the candidate. Messages have two priorities: system notices, reminders and the first contact are reserved before everything else, so a broadcast to thousands never delays the first SMS to a new applicant.

The queue is the messages table. Once a second the worker asks which companies have a message due and reserves what each may send (send-queue.runner.ts). Two things on this path belong to the rules above:

  • The rules are read again when the message leaves. A scheduled message may leave hours after it was accepted. At the reservation the worker reads consent, phone, archiving and suppression again, and cancels what is no longer allowed. It reads the status once more right before the provider call, so a STOP that arrives in between still stops the message.
  • A doubtful SMS is not repeated. A temporary failure is retried after 30 seconds, 2 minutes, 10 minutes and 30 minutes, and the fifth failure ends the message as failed. An SMS provider that does not answer in 15 seconds ends the message as failed at once, with no retry: the provider may have accepted it, and a second call could deliver the same text twice.

An automatic email (automation, sequence, broadcast) carries a footer with an unsubscribe link of its own. The page of the link runs on the careers site, which is why a company without a careers page address cannot send automatic email. email_suppressions holds the addresses that unsubscribed, bounced or complained; bounces and complaints arrive by webhook from the provider. Any row for an address blocks every email to it, including one typed by a recruiter.

An address that carries a token (unsubscribe, scheduling, signing, full application, candidate area) is never stored in messages.body. The row keeps [link], and the real link is produced when the message leaves. Email attachments are produced at the same moment and are not stored in the row either. See ADR-0018.

The sending and receiving services know two interfaces, SmsProvider and EmailProvider (providers.ts). An adapter carries a message and translates the format of its provider. It applies no rule and, apart from the provider opt-out above, does not touch the database.

Channel Adapters Default
SMS simulator, twilio simulator
Email outbox, smtp, ses outbox
  • Chosen by configuration. The API does not start when a real provider is selected and one of its settings is missing.
  • Webhooks are verified. A status notice or a received message from a provider is accepted only after its signature is checked, and the database finds the company from the number, the reply token or the provider message id of the notice.
  • The simulator is a full stand-in. It accepts every message, keeps it locally, and the worker marks it delivered shortly after. Replies, STOP and failures are injected through test routes that do not exist in production. The whole path above, including consent, window and cap, runs the same with the simulator.
  • The screen says so. With the simulator, the Messaging tab of Platform > Integrations shows “Simulator mode: messages are not delivered to real phones.”

An SMS number is assigned to a company by the platform team, and with a real provider it must be marked as approved before the first SMS leaves.

Test file What it proves
apps/api/test/messaging-send.test.ts Each refusal is born canceled with its reason and no provider is called; the same idempotency key sends once; the window and the cap; templates and variables; the private writer and the keyword reply service are not exported by the module.
apps/api/test/messaging-queue.test.ts The limit per second and the priorities; the re-read at the reservation; what each provider answer does to the message; the simulator.
apps/api/test/messaging-inbound.test.ts The keywords, compared with the whole text; receiving; stop, start and help; status notices; the audit row of a message typed by a user.
apps/api/test/messaging-inbound-consent-race.test.ts A STOP that arrives while another path writes a consent still wins.
apps/api/test/messaging-time.test.ts The time zone of a candidate (state, then area code, then company), the window across a daylight saving change, and a state in two zones.
apps/api/test/unsubscribe.test.ts, message-links.test.ts The footer, the public unsubscribe routes, and that a stored message keeps [link] instead of an address with a token.
apps/api/test/twilio-signature.test.ts, twilio-webhook.test.ts, twilio-send.test.ts The webhook signature, the limits of the webhook, and the Twilio adapter against recorded requests, including a phone the provider already blocked.
apps/api/test/ses-webhook.test.ts, ses-send.test.ts, smtp-send.test.ts The same for the email adapters: replies, bounces and complaints.
apps/api/test/import-consent.test.ts Consent of imported candidates and of consent recorded by hand.
packages/db/test/isolation-wave03-messaging.test.ts, wave02-public-functions.test.ts The database side: isolation of the messaging tables between companies, and the trigger that keeps the current consent of a candidate, which the application role cannot run or bypass.
  • No override. Not even an owner can text a candidate who has no recorded consent or who asked to stop. The way forward is to record a new consent, with its source.
  • Messages past the cap are lost. An automatic SMS that exceeds the daily cap is discarded and shown as canceled. It is not sent the next day.
  • Sending is not instant. A message is queued and picked up by a pass of the worker that runs once a second. The user sees it as queued, then sent, then delivered when the provider confirms.
  • The window follows the record. The time zone comes from the state or the phone number of the candidate. A candidate who moved without updating the record is treated as being in the old zone.
  • Text only. SMS carries no picture, and email is plain text. With the smtp adapter the system does not receive replies: they go to the reply address of the company.
  • The real providers are Not verified. The adapters for Twilio, SMTP and Amazon SES are tested against recorded requests and local test servers, not against live accounts. The default configuration runs the simulator.
  • The texts are a preview. Consent wording, keyword replies and the limits of the window are marked as a regulatory preview until validated.