Concepts
How Deckle works
A tour of Deckle's architecture — sending from your own domain on top of AWS SES, with an event-driven core that turns a send API into a full marketing platform.
Deckle is a thin, opinionated layer over Amazon SES plus an event-driven core. You send from a domain you own and verify, Deckle handles rendering and delivery, and every delivery signal flows back to update status, protect your reputation, and drive automations.
The big picture#
Deckle runs on Model A: you send from your own verified domain on top of AWS SES. There is no shared sending pool. Every email leaves under your domain’s DKIM signature, so deliverability rides on your reputation and yours alone.
That is the key difference from shared-pool providers. When many senders share the same IPs and envelope domain, one bad actor’s spam complaints can quietly drag down everyone else’s inbox placement. With Model A, your reputation is isolated: nobody else’s list hygiene can poison your delivery, and you carry the full, portable value of the domain reputation you build.
On top of delivery, Deckle layers an event-driven core. Contacts, named events, segments, automations, and campaigns all sit above the same send pipeline, so the same infrastructure that delivers a password reset can also power a lifecycle automation.
You own the domain, Deckle owns the plumbing
Because you send from your own domain, you keep your reputation even if you ever leave. Deckle creates the SES identity and shows you the DNS records to publish — see Domains overview.The send pipeline#
Every email — whether it comes from the API, the SDK, the SMTP relay, a campaign, or an automation — travels the same path. Here is what happens between your request and the inbox.
Validate the request
Deckle checks the required fields (from, to, subject, and one of html or template) and confirms the from address belongs to a verified domain in the project. Invalid requests are rejected before anything is sent.
Check the suppression list
The recipient is checked against the project’s suppression list. If the address was hard-bounced, complained, unsubscribed, or added manually, the send is rejected with a 422 so you never re-mail an address that should stay quiet.
Render to clean HTML and plain text
If you passed a template, Deckle renders its React Email source with your variables into deliverability-safe, inline-CSS HTML, and generates a plain-text alternative automatically. Template sends also get open-pixel and click tracking injected; raw html sends are delivered as-is, uninstrumented.
Deliver through AWS SES
The finished message is handed to AWS SES and sent from your verified domain under its DKIM signature. Deckle records an email log with an id (email_…) and an initial status.
Receive delivery signals over SNS
SES reports what happened — delivery, bounce, or complaint — back to Deckle through an SNS notification. This is where the async half of the pipeline begins: the outcome arrives moments (or, for some bounces, longer) after the accept.
Update status, auto-suppress, and fire webhooks
Deckle updates the email’s status from each notification, auto-suppresses hard bounces and complaints so they are never mailed again, and fires the matching webhooks to your endpoints (email.delivered, email.bounced, email.complained, and, for tracked template sends, email.opened and email.clicked).
Not configured yet? You still get a clean accept
Before delivery is fully wired up, a valid send returns202 — accepted and queued — instead of failing. Your integration can be built and tested end to end while DNS and SES finish verifying.The event-driven core#
Delivery is only half of Deckle. The other half is a small set of primitives that turn raw sends into a marketing platform. They all revolve around one idea: a contact is keyed by email, and things happen to it over time.
Contacts#
A contact is an email address plus optional name, subscription state, and custom data. Email is the identity, so the same person is one contact whether they arrived from a signup form, a CSV import, or an API call. Contacts are unlimited — Deckle bills per send, not per contact.
Events#
Events are named actions tied to a contact by email — user.signed_up, order.completed, anything meaningful in your product. You record them once and they do double duty: they build the contact’s activity timeline and they drive everything reactive downstream.
Automations#
Automations are workflows that react to events (or to a contact subscribing). A trigger starts an enrollment, and ordered steps — send an email, wait for a delay, wait for another event, branch on a condition, or run an action like adding a tag — carry the contact through the flow. This is the primitive that connects “what a user did” to “what email they get next.”
Segments#
Segments are live, rule-based groups of contacts. Instead of a static list, a segment is a set of AND/OR rules over attributes, events, and engagement — membership recalculates as contacts change. Use one as a campaign target.
Campaigns#
Campaigns broadcast a single message to your whole audience or a segment, one-off or scheduled, with optional A/B subject lines. Under the hood, a campaign fans out into the very same send pipeline above — every recipient is validated, suppression-checked, rendered, delivered, and tracked exactly like a one-off send.
One pipeline, many entry points
Transactional API calls, SMTP, campaigns, and automation steps all converge on the same validate → render → SES → SNS path. Learn it once and it explains every kind of send Deckle makes.What this means for you#
Because these pieces share one foundation, you can start small and grow without switching tools:
- Send a single transactional email today with nothing but an API key and a verified domain.
- Start recording events, and those same signals populate timelines and wake automations later — no re-instrumentation.
- Layer on segments and campaigns when you are ready to broadcast, reusing the reputation and deliverability you have already built.
Next steps#
Dig into the primitives that make the pipeline and the event-driven core concrete.