Email engine

Every email Arc CMS sends goes through one engine: pick a provider, set a brand kit, edit templates in a block editor, and read what happened to each message in the email log.

What it is

The engine is the part every other email feature sends through. It has these pieces:

The Email menu is named Email + SMS while the SMS feature is on.

Every email has a category. transactional email (codes, receipts) ignores marketing consent. marketing email needs the recipient to be subscribed and must contain an unsubscribe link. Broadcasts, drip sequences and announcements are Email marketing; form emails are Signup forms. Both send through this engine.

Turn it on or off

The engine is always on: it is core, not a switchable feature, and every app has it. What you control is at run time, on Admin, Settings, Email Settings:

• The master switch (Email Enabled) turns all sending on or off. It cannot be turned on until a provider is set up. While it is off, every send is written to the email log as skipped with the reason email_disabled.
• Email Features turns one kind of email off and leaves the rest alone. A blocked send is logged as skipped, reason feature_disabled. Admin alerts is the exception: while it is off, the alerts are not created at all, in the app or by email.

Test sends and emails sent by Automations have no switch of their own under Email Features; the master switch still stops them.

Set it up

1. Choose a provider. Open Admin, Settings, Email Settings and pick one:

   Provider	What it needs	Default limits
   SMTP	Host, port (587 by default), secure on or off, user, password	1 per second
   Gmail	A Gmail address and a Google app password	1 per second, 500 a day
   Resend	An API key	2 per second, 100 a day
   Debug Provider (Log Only)	Nothing	None

   For a real provider, click Send a Test Email and give an address: the test sends a real message through the provider, and Save Settings stays disabled until it passes. The Debug Provider needs no test.

2. Fill in the sender. Sender name and email are copied into the default templates when they are created, and used for test sends. Reply-to applies to every send; BCC (a copy of every email) applies with SMTP and Gmail. Change the per-second, per-hour and per-day limits if your plan allows more. A send over the limit waits and is tried again later.

3. Save. Choosing a provider (or clicking Configure Email) and then saving also turns email on, so the master switch needs no separate click. Switch it off with the toggle at the top of the page; saving after that leaves it off.

4. Set the public address for email links, if you use your own domain. Unsubscribe and preference links are built on liveUrl in the Settings/email document, or, when that is empty, on live_url in functions/src/constant.ts, or, when that is empty too, on the install's Hosting address, https://<hosting site>.web.app/. So a new install needs nothing here until it has a custom domain. The admin page has no field for it: add liveUrl (for example https://example.com/) to the document in the Firebase console. Saving the page keeps it. With Hosting turned off and nothing set, the links come out relative and do not work.

5. Set the brand kit on Admin, Email, Brand Kit: logo URL and width, colors, font, footer text, postal address and social links. The preview updates as you type.

Templates need no setup step. The default templates are created the first time something needs one (the first sign-up, the first notification email, the first digest), and opening Email, Announcements creates any that are missing. Creating them never overwrites a template that exists.

Use it

Edit templates in the composer

1. Open Admin, Email, Composer. It lists one template per type. Templates of a feature that is off (form or payment emails) are not listed.

2. Pick a template, or click New email. A new email gets a unique type such as custom_1759200000000; the Type column shows it as "Custom 1759200000000".

3. Set the title, subject and category, then build the body from blocks: heading, paragraph, image, button, divider, spacer, columns, social links and raw HTML.

4. Type # in a text field to pick a merge tag such as ##NAME##. The tags offered depend on the template type; the full list is in Email merge tags.

5. Save. The composer stores the block design and the finished HTML, wrapped in the brand kit.

6. Click Send test to send the compiled email to an address. Its subject starts with [TEST], and it is logged like any other email.

A marketing template cannot be saved without ##UNSUBSCRIBE_LINK##. The brand kit footer carries it by default.

Transactional emails

To stop one of these emails without touching code, turn its template off: payment emails have a switch each on Settings, Payments, and form emails on the form's Email Templates page. For the others, set the template's isActive field to false in the Firebase console. Its sends are then logged as skipped, reason template_inactive.

The admin digest emails every admin a count of new sign-ups, successful payments and failed emails from the last 24 hours. It has no switch on the admin page: set adminDigest to { enabled: true, hourUtc: 8 } in the Settings/email document. The job runs every hour and sends in that hour (UTC).

How a send works

Every email is queued by one function, queueEmail() in functions/src/email-core/queueEmail.ts. It checks, in order: the master switch, the email's feature switch, whether the template is active, whether an admin disabled the contact (with Audience on), marketing consent (marketing only), and the suppression list. A send that fails a check is still written to the log, with the reason. A send that passes is written as pending, and a trigger, onEmailLogCreate, sends it. An email queued with sendNow: true, such as a sign-up code, is sent by the call that queued it instead, which saves the seconds the trigger can take to start. The trigger still runs and sends it only if that call did not.

A failed send is retried with growing delays (10, then 20 minutes) up to 3 attempts, then marked failed. A send over the rate limit is marked deferred and tried again after 15 minutes. The retryPendingEmails job picks both up every 5 minutes.

Read the email log

Admin, Email, Email Logs lists every email with its status. Open one to see the exact subject and HTML that were sent, the merge tags used, and any tag that had no value.

Logs older than 60 days are deleted every night at 02:00 UTC. Change the number of days, or turn this off, under Auto-Purge Email Logs on the Email Settings page. Purge Old Logs on the log page deletes them now.

Unsubscribe and preferences

The brand kit footer carries two links by default: ##UNSUBSCRIBE_LINK## and ##PREFERENCES_LINK##. Each carries a token signed with the site's secret, so nobody can build one for someone else's address.

• Unsubscribe (/unsubscribe?e=...&t=...) adds the address to the suppression list and shows a confirmation page. Marketing emails also carry the List-Unsubscribe headers, so mail apps can offer their own one-click button.
• Preferences (/email-preferences?e=...&t=...) shows whether the person gets marketing email and lets them turn it off or back on.

A suppressed address gets no marketing email and still gets transactional email, such as codes and receipts. With Audience on, the contact's consent changes as well, and with Email marketing on, an unsubscribe ends their drip sequences. A bounce or complaint reported by the provider webhook is recorded on the email log only; to stop mailing an address that bounces, suppress its contact in Audience.

Extend it

Send email from your own Cloud Functions (in functions/src/custom/) through queueEmail(), never by writing to EmailLogs: a test fails if any file outside functions/src/email-core/ creates an email log. Create the template in the composer, copy its type, and load it by that type:

import { db } from '../init.js';
import { queueEmail } from '../email-core/queueEmail.js';

export async function sendShippedEmail(toEmail: string, tracking: string) {
  const snap = await db.collection('EmailTemplate').where('type', '==', 'custom_1759200000000').limit(1).get();
  if (snap.empty) return;
  const t = snap.docs[0].data();
  const settings = (await db.collection('Settings').doc('email').get()).data() ?? {};
  await queueEmail({
    source: 'event',
    category: 'transactional',
    toEmail,
    senderEmail: t.senderEmail || settings.senderEmail,
    senderName: t.senderName || settings.senderName,
    subject: t.subject,
    template: t.template,
    type: t.type,
    templateIsActive: t.isActive !== false,
    data: { TRACKING: tracking },   // fills ##TRACKING##
  });
}

A template created with New email has no sender of its own, and queueEmail() sends with exactly the sender you pass: fall back to the sender on Email Settings, as above.

• The result says what happened: { status: 'pending' | 'skipped' | 'suppressed', skipReason }.
• Add sendNow: true for an email someone is waiting for on screen, such as a code: your function sends it before it returns, not the trigger. Leave it off for everything else, so a burst of emails does not hold up your function.
• Pass dedupeKey from a trigger that may run twice: the same type and key never queue a second email.
• To let admins decide which email goes out when something happens in your app, emit an event instead and let them map it in Automations.
• To reach a signed-in user in the app and by email, create a notification (see Notifications).

Where your functions go and how they deploy: Write your own Cloud Functions.

What it stores

Nothing is kept in Storage. The Cloud Functions, each deployed as arccms-<name>:

All collections: Data model. All functions: Cloud Functions.

Who can do what

Roles and how they are checked: Roles and claims.

Troubleshooting