Email and WhatsApp messages

Mooflair sends email through Mailgun and WhatsApp through Beamvia: sign-up and password codes, workspace invites, new members, ownership changes and security notices. Code never calls a provider directly. It queues a message, and the message service on the server sends it, retries it and records what happened. Admins see every message in Admin › Delivery › Messages.

How a message travels

1. Code calls messageQueue({ template, to, data }) (src/controllers/message/queue.ts). It picks the channels, inserts one Message per channel with status queued, and returns at once.
2. The message service (src/services/message, started by server.ts) claims the next due message atomically (findOneAndUpdate with a 60-second lease), so two servers never send the same one.
3. It renders the template in the recipient's language and sends it through the channel's provider. Success sets sent with the provider's id.
4. The provider's webhook later moves it forward: delivered, read, or failed / bounced / complained. Webhooks only update; they never send.

Who gets which channel

• to: { userId }: critical templates (codes, password, security, ownership) go to every channel the person has: email (if not bounced) and WhatsApp (only a verified number). Other templates go to email, else WhatsApp.
• to: { email } or to: { phone }: that one channel (sign-up codes, invites to people without an account, admin tests).
• A channel that is off or not set up is skipped. If no channel is left, nothing is queued and the caller says so.

Retries and pace

• Errors retry after 30 s, 2 min, 10 min, 1 h, up to 5 tries. Beamvia's plan (402) and daily quota (429) errors wait a day. Errors that won't improve (400/401/403, channel off) fail at once.
• Each server runs rate.concurrent workers per channel, paced to rate.second sends per second. A change to concurrent applies after a restart.
• At most rate.recipient.hour messages reach one address or number an hour (critical ones skip this cap); extra ones wait 10 minutes.
• Delivery is at least once: a crash between the provider's answer and our update can repeat a send after the lease runs out.
• On shutdown the service stops claiming, finishes what it's sending, and hands back any lease.

Codes are never stored in clear

Templates list the data keys to mask (the OTP code). Those values are sealed with the encryption key while queued, and replaced by •••••• once sent or failed, in the data, the subject and the preview. Messages with codes can't be retried or resent from admin.

Templates

One folder per template under src/lib/message/template/<domain>/<name>/index.tsx, listed in src/lib/message/template/index.ts, keyed <domain>.<name>. Each has isCritical, mask, sample data and a render per channel:

• email: a React Email component in the shared layout (template/layout), rendered to HTML and plain text.
• whatsapp: short text with WhatsApp formatting.

Text lives in i18n under message.<domain>.<name> (en, id) and is rendered in the recipient's language (their account language, else the one given).

Add one: its folder, its text in both message files, one line in the list.

Providers

Plug-and-play like payment methods: src/lib/message/provider/<key>/index.ts with the channels it serves, isReady, send and webhook, listed in provider/index.ts. Each channel picks its provider in message.<channel>.provider.

Beamvia runs on the WhatsApp Web protocol, so a number can be banned: keep the pace low; codes can always go by email.

Admin pages

• Delivery › Messages (/admin/delivery/message): counters (queued now, sent today per channel, failure rate and failures in 24 h), the queue and history in one table with filters (status, channel, template, recipient, user, workspace), live every 10 seconds. Click a recipient for the detail: the rendered email in a sandboxed frame or the WhatsApp text, the timeline, the error, and Retry (failed), Cancel (queued), Resend (a new message). The sidebar shows the failures of the last 24 hours.
• Configuration › Messages › Email / WhatsApp: the provider (Mailgun / Beamvia, or the server console in development), turn the channel on, keys (never shown back; blank keeps the saved one), sender and reply-to (email), pace, the webhook URL to paste in the provider, and the last message's status.
• Configuration › Messages › Templates: every template per channel and language with sample data, and Send test to an address or number (queued like any message).

Configuration

History is kept 90 days (critical messages 30 days).

FAQ

Can I sign up locally without Mailgun or Beamvia?

Yes. Set the channel's provider to Server console (development only) in Admin › Configuration › Messages › Email or WhatsApp. Codes then appear in the dev server's output. It never sends in production.

Why did a message go to email and not WhatsApp?

Non-critical messages go to one channel, email first. WhatsApp also needs a verified number.

Does the bell use this queue?

No. In-app notifications are written straight to the database; the queue is for email and WhatsApp.