Send an email

How to send a transactional email from backend code, for example a "your export is ready" message. Email explains the two mail systems, the queue and SMTP setup; this page is the checklist.

Steps

Import EmailModule into your feature module and inject EmailService into your service. The snippet is in Email, "Sending an email from a service".
Call queue(), not send():
```
async queue(options: QueueEmailOptions): Promise<EmailJobRow> {
```
queue() inserts an email_jobs row and returns at once. The EmailProcessor cron sends pending jobs in batches and retries a failure with backoff. send() waits on SMTP inside the request and never retries. Use queueBulk() for many recipients; pass campaignId / campaignName to group a send in the backoffice email stats.

queue() writes through this.db, not your transaction's trx. If the email belongs to a transaction, call queue() after it commits, or a rolled-back change still sends its email.
Build the HTML yourself. The backend has no template system: html is a string you pass in, its length capped by QueueEmailOptionsSchema in email.schemas.ts. Two examples to copy from:
- frontend/lib/magic-link-email.ts: the sign-in email, a full table-based HTML layout with inline styles. It belongs to NextAuth on the frontend and does not go through EmailService, but its markup is a working starting point.
- The seed's "Welcome Series" campaign in backend/src/scripts/seed.ts: a minimal body, '<h1>Welcome!</h1><p>Thanks for joining CrabStack. ...</p>'.
Escape anything a user typed before you put it in the HTML, with escapeHtml from backend/src/common/escape-html.ts.
Write a test. In a unit spec, mock EmailService and assert your service called queue with the right to, subject and html. To prove the whole path against a real database, follow backend/src/email/email.service.integration.spec.ts, which replaces the SMTP transporter with a recorder:
```
(service as unknown as { transporter: unknown }).transporter = {
  sendMail: async (m: { to: string }) => {
    sent.push(m);
    return {};
  },
};
```
Look at it locally. Run npm run dev:email in backend/ (MailDev: SMTP on port 1025, inbox at http://localhost:1080). The backend's SMTP defaults already point there. Trigger your code, wait for the next batch, and the message shows up in the inbox.
Run ./verify.sh.

What the test run found

The template's own specs covered processBatch and queueBulk (through the MCP tool spec) but no spec called queue() itself. A test added to email.service.integration.spec.ts in the test clone called queue(), ran processBatch(), and checked the recorder received the message and the job was marked sent: verify all green.

Steps

Import EmailModule into your feature module and inject EmailService into your service. The snippet is in Email, "Sending an email from a service".

Call queue(), not send():

async queue(options: QueueEmailOptions): Promise<EmailJobRow> {

queue() inserts an email_jobs row and returns at once. The EmailProcessor cron sends pending jobs in batches and retries a failure with backoff. send() waits on SMTP inside the request and never retries. Use queueBulk() for many recipients; pass campaignId / campaignName to group a send in the backoffice email stats.

queue() writes through this.db, not your transaction's trx. If the email belongs to a transaction, call queue() after it commits, or a rolled-back change still sends its email.

Build the HTML yourself. The backend has no template system: html is a string you pass in, its length capped by QueueEmailOptionsSchema in email.schemas.ts. Two examples to copy from:

frontend/lib/magic-link-email.ts: the sign-in email, a full table-based HTML layout with inline styles. It belongs to NextAuth on the frontend and does not go through EmailService, but its markup is a working starting point.
The seed's "Welcome Series" campaign in backend/src/scripts/seed.ts: a minimal body, '<h1>Welcome!</h1><p>Thanks for joining CrabStack. ...</p>'.

Escape anything a user typed before you put it in the HTML, with escapeHtml from backend/src/common/escape-html.ts.

Write a test. In a unit spec, mock EmailService and assert your service called queue with the right to, subject and html. To prove the whole path against a real database, follow backend/src/email/email.service.integration.spec.ts, which replaces the SMTP transporter with a recorder:

(service as unknown as { transporter: unknown }).transporter = {
  sendMail: async (m: { to: string }) => {
    sent.push(m);
    return {};
  },
};

Look at it locally. Run npm run dev:email in backend/ (MailDev: SMTP on port 1025, inbox at http://localhost:1080). The backend's SMTP defaults already point there. Trigger your code, wait for the next batch, and the message shows up in the inbox.

Run ./verify.sh.

What the test run found

The template's own specs covered processBatch and queueBulk (through the MCP tool spec) but no spec called queue() itself. A test added to email.service.integration.spec.ts in the test clone called queue(), ran processBatch(), and checked the recorder received the message and the job was marked sent: verify all green.

Send an email

Steps

What the test run found

Related

Send an email

Steps

What the test run found

Related