What it is
A submodule that connects a SpacetimeDB application to the Resend email delivery service, handling outbound sending, delivery tracking, and webhook ingestion. It lives inside your module's schema and keeps all email state, credentials, and event history in your own database tables.
Where it fits
- Transactional email: An app that sends welcome messages, password resets, or receipts and needs delivery confirmation stored alongside its other application data.
- Multi-tenant SaaS: A product where each organization or user should only see their own email history, enforced at the database level rather than in application code.
- Audit-sensitive workflows: A compliance-conscious app that needs an append-only log of every delivery event, including delays, bounces, and complaints, for later review or replay.
- Webhook-driven status updates: An app that wants delivery status to update automatically in the database as Resend fires events, without polling an external API.
- Operator-controlled sending: A platform where only privileged identities may trigger email sends or inspect raw delivery data, while end users see only scoped views of their own history.
How it works
When your application requests an email, the submodule records it immediately in your database with a queued status, then forwards the request to Resend. From that point on, delivery status lives in your database and is updated by incoming webhook events from Resend. Each event is verified for authenticity before being applied, and the submodule ensures that status only moves forward: a later delivery stage cannot be overwritten by an earlier one, and duplicate events are ignored.
Webhook events arrive over HTTP and are processed as database transactions. The submodule stores every event it receives, whether it applies to a known email state or not, so you have a complete forensic record. Events that represent terminal outcomes (delivered, bounced, failed) update the main status field, while engagement signals like opens and clicks are recorded as separate flags without disturbing delivery status.
All email content, recipient addresses, credentials, and raw webhook payloads are kept in private tables that your application code cannot subscribe to directly. Your module is expected to expose narrower, caller-scoped views so that each user or tenant sees only their own history. This separation means the submodule handles the mechanics of sending and tracking while your application retains full control over authorization and what data is visible to whom.
