Email & Mail Worker

Receive inbound mail through the Cloudflare worker and send outbound mail through the platform pipeline. This guide follows version 3.1.7 (03acdf712c).

For broadcasts, see Broadcasts & Notifications.

Inbound path

1. cloudflare/mail-worker/src/ (index.ts, parse.ts, storage.ts, address.ts, routes.ts, hmac.ts) parses the message, derives the tenant from the address, queues MAIL_QUEUE, and delivers with HMAC headers (x-erxes-signature, x-erxes-timestamp) plus a DLQ (erxes-mail-dlq).
2. backend/plugins/frontline_api/src/modules/integrations/mail/ receives at POST /mail/receive (routes.ts, mounted in src/routes.ts). controller/receiveMessage.ts verifies the signature headers, parses tagged addresses, threads via findConversationByReplyTag/findRelatedConversation, stores the message, and emits receiveInboxMessage plus pConversationClientMessageInserted.
3. messageBroker.ts manages integration lifecycle (mailCreateIntegration, mailUpdateIntegration, address building, indexes, sendability checks).

Outbound path

• Core helpers: backend/core-api/src/utils/email/ (links.ts for gateway, read-file, unsubscribe, tracker URLs; senders.ts, ramp.ts, intake.ts, scope.ts).
• Broadcast sending builds SES parameters in backend/core-api/src/modules/broadcast/utils/email.ts.
• Auth mail (magic links) sends via SendGrid in backend/core-api/src/modules/auth/utils.ts.

Verify

1. Send a test message to a tagged inbound address and confirm it threads to the right conversation.
2. Replay the same payload and confirm idempotency (no duplicate conversation).
3. Send an outbound test and confirm unsubscribe and tracking links resolve through the gateway URL.

Source references

• Mail worker entry.
• Mail receive controller.