# Deckle documentation — full text

> Every documentation page, concatenated. Index: https://app.getdeckle.com/llms.txt


========================================================================
URL: https://app.getdeckle.com/docs/introduction
Section: Get started
========================================================================

Get started

# Deckle documentation
Deckle is a design-first email platform — the developer experience of a modern email API with the audience, templates, and automations of a marketing tool. Send transactional and marketing email from your own domain.
Everything you send goes out from a domain you own and verify, so your reputation stays yours. Start with a single API call, then grow into contacts, campaigns, and event-driven automations without changing tools.

```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Welcome to Acme 👋",
html: "<h1>Hey Jane</h1><p>Thanks for joining.</p>",
});
```
New to Deckle?
Follow the Quickstart to send your first email in under five minutes, then verify a domain to start sending to real inboxes.Built for LLMs. For all documentation in an index, see llms.txt. To read the full text of the documentation, see llms-full.txt.

## Start building
Jump straight to what you need.
QuickstartCreate a key and send your first email with the SDK, HTTP, or SMTP.
Send emailTransactional sends, templates, variables, attachments, and idempotency.
AudienceManage contacts, track events, build segments, and handle suppressions.
AutomationsTrigger multi-step email flows from events and subscriptions.
Domains & deliverabilityVerify a domain with DKIM, SPF, and DMARC to protect your reputation.
API referenceEvery endpoint, parameter, and response for the Deckle REST API.

## What you can build
Deckle covers the full lifecycle of the email you send — from a one-off password reset to a recurring newsletter to a lifecycle automation that reacts to what your users do.
Transactional emailReceipts, magic links, and alerts over the API, SMTP, or SDK.
Marketing campaignsBroadcast to your whole list or a segment, with A/B subject lines.
Beautiful templatesA gallery of clean, deliverability-safe templates you can brand and reuse.

## How it fits together
Under the hood, Deckle runs on Amazon SES and layers an event-driven core on top: contacts are keyed by email, events record what they do, and automations react to those events. That single primitive is what turns a send API into a marketing platform. Read How Deckle works for the full picture.
Base URL
The API is served at https://app.getdeckle.com/api/v1. All requests are authenticated with a secret API key — see API keys.


========================================================================
URL: https://app.getdeckle.com/docs/quickstart
Section: Get started
========================================================================

Get started

# Quickstart
Create an API key and send your first email in a few minutes — with the SDK, plain HTTP, or SMTP.
This guide gets a single email out the door. In test mode you can start immediately; to reach real inboxes you’ll verify a sending domain at the end.

### Create an API key
In the dashboard, open Developers → API keys and create a key. Pick the Test environment to experiment safely. Copy the key — it starts with sk_test_ and is shown only once.
Store it safely
Deckle stores only a hash of your key. If you lose it, revoke the key and create a new one. Never commit keys — load them from an environment variable.

### Install the SDK (optional)
The official Node.js SDK is zero-dependency and works on Node 18+, Deno, Bun, and the browser. Prefer raw HTTP? Skip ahead to the next step.
bash
```
npm install @deckle/sdk
```

### Send an email
Set your key as an environment variable, then send:

```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

const { id } = await deckle.emails.send({
from: "Acme <onboarding@acme.com>",
to: "delivered@resend-like.simulator", // use success@simulator.amazonses.com in test mode
subject: "Hello from Deckle",
html: "<h1>It works!</h1><p>Your first Deckle email.</p>",
});

console.log("Queued:", id);
```
Test mode
A sk_test_ key can only send to the AWS SES simulator (for example success@simulator.amazonses.com) or to your own verified domains — never a real inbox. That makes it safe to run in CI.

### Verify a domain to go live
To send to real recipients, add and verify a sending domain, then switch to a sk_live_ key. Deckle generates the DKIM, SPF, and DMARC records for you to publish at your DNS provider.

- Open Domains and add your domain.
- Publish the DKIM, SPF & DMARC records.
- Wait for verification (auto-polled), then send from an address on that domain.

## What’s next
You’ve sent an email. Here’s where to go from here.
Send your first emailA deeper walkthrough — templates, variables, and inspecting the result.
API keysTest vs live keys, rotation, and keeping secrets safe.
DomainsVerify a domain so your mail lands in the inbox, from your own reputation.
API referenceEvery endpoint, parameter, and response.


========================================================================
URL: https://app.getdeckle.com/docs/send-your-first-email
Section: Get started
========================================================================

Get started

# Send your first email
A hands-on walkthrough: send raw HTML, then a branded template with variables, and inspect what happened.
If you followed the Quickstart, you already have a key. Here we go a little deeper — the same send call powers everything from a password reset to a receipt.

## Prerequisites

- An API key (create one) exported as DECKLE_API_KEY.
- A verified sending domain for live sends — or use test mode against the SES simulator.

## Send a raw HTML email
The only required fields are from, to, subject, and one of html or template. The from address must be on a domain you’ve verified.

```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

const result = await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
reply_to: "support@acme.com",
subject: "Welcome to Acme 👋",
html: `
<h1>Welcome, Jane</h1>
<p>Thanks for signing up. Your account is ready.</p>
`,
text: "Welcome, Jane. Thanks for signing up.",
});

console.log(result.id, result.status);
```
Always include plain text
Pass a text alternative alongside html. Multipart emails look trustworthy to spam filters and render everywhere. When you send a stored template, Deckle generates the text part for you.

## Send a template with variables
Instead of inline HTML, reference a stored template by id and pass variables. Deckle renders the template, fills {{placeholders}}, and injects open + click tracking automatically.
template.ts
```
await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Welcome, {{first_name}}",
template: "tmpl_welcome_01",
variables: { first_name: "Jane", plan: "Pro" },
});
```
See Templates and Variables & personalization for the full syntax, including fallbacks like {{first_name | "there"}}.

## Inspect the result
Every send returns an id. Use it to fetch the current status and engagement counts, or list recent sends.
ts
```
const email = await deckle.emails.get(result.id);
// { id, to, subject, status: "delivered", opens: 1, clicks: 0, ... }

const recent = await deckle.emails.list({ status: "sent", limit: 20 });
```
You’ll also see every send in the dashboard under Developers → Email logs, with delivery, open, click, bounce, and complaint status as it arrives.

## Next steps
TemplatesReuse designed emails and brand them per project.
ContactsStore your audience and personalize from their data.
AutomationsTrigger flows from events like sign-ups and purchases.


========================================================================
URL: https://app.getdeckle.com/docs/concepts/how-deckle-works
Section: Core concepts
========================================================================

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 returns 202 — 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.
Projects & environmentsHow projects isolate your data and how Test and Live environments keep sends safe.
Send with the SDKPut the send pipeline to work from Node with @deckle/sdk.
EventsRecord named actions that power timelines, segments, and automation triggers.


========================================================================
URL: https://app.getdeckle.com/docs/concepts/projects-and-environments
Section: Core concepts
========================================================================

Concepts

# Projects & environments
A project is an isolated workspace, and every project has a Test and a Live environment. Which one you send from is decided entirely by the key you use.
Everything in Deckle lives inside a project, and every project ships with two environments. You don't configure environments separately — you pick one by using a sk_test_ or sk_live_ key, which keeps testing safely away from real inboxes.

## Projects
A project is a self-contained workspace. Each one owns its own data and never shares it with another project, so you can keep separate apps, brands, or clients fully isolated under a single account.
Everything below is scoped to the project you're in:

- Contacts — your audience, keyed by email, with events and activity timelines.
- Templates — the React Email templates you send and brand.
- Domains — the verified domains you're allowed to send from.
- API keys — the secret keys that authenticate every request.
- Events — the named actions that power segments and automations.Because keys are scoped to a project, a key from one project can never read or send on behalf of another. Create and switch between projects with the project switcher in the dashboard top bar.

## Test and Live
Every project has two environments, Test and Live. You don't select an environment in a settings page — you select it by choosing which key you send with. A sk_test_ key targets the Test environment; a sk_live_ key targets Live.

```
import { Deckle } from "@deckle/sdk";

// A test key sends into the Test environment.
const test = new Deckle("sk_test_...");
await test.emails.send({
from: "Acme <hello@acme.com>",
to: "success@simulator.amazonses.com",
subject: "Sandbox check",
html: "<p>This never reaches a real inbox.</p>",
});

// A live key sends into the Live environment.
const live = new Deckle("sk_live_...");
await live.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Welcome to Acme 👋",
html: "<h1>Hey Jane</h1>",
});
```
In the dashboard, the Test/Live toggle sits in the top bar. It filters what you see — emails, logs, and reports — to the environment you're viewing, so a test send never clutters your live analytics.

### What Test can do
The Test environment is a sandbox. A sk_test_ key can only deliver to two kinds of recipient:

- AWS SES simulator mailboxes, such as success@simulator.amazonses.com, bounce@simulator.amazonses.com, and complaint@simulator.amazonses.com.
- Addresses on the project's own verified domains.This lets you exercise the full pipeline — templates, variables, webhooks, and bounce or complaint handling — without any risk of reaching a real person.
Test keys are sandboxed
A sk_test_ key can never send to arbitrary real inboxes. It reaches only the SES simulator mailboxes or your project's verified domains. Any other recipient is rejected. To email real people — and to run campaign or broadcast sends — you must use a sk_live_ key.

### What requires Live
ActionTestLive
Transactional send to the SES simulatorYesYes
Send to your own verified domainYesYes
Send to arbitrary real inboxesNoYes
Campaign / broadcast sendNoYes

## Switching projects
Use the project switcher in the dashboard top bar to move between projects or create a new one. Switching changes everything the dashboard shows — contacts, templates, domains, keys, and logs all belong to the active project.
Over the API there's nothing to switch: the project (and its environment) is determined by the key on the request. Point your app at a different project by swapping the key, typically through an environment variable such as DECKLE_API_KEY.
One key per environment per deploy
Give each deploy its own key: a sk_test_ key in local and staging, a sk_live_ key in production. Store both in API key secrets, never in source control.

## Next steps
API keysCreate, scope, and rotate the test and live keys that pick your environment.
Send with the SDKSend your first email from a project using the Node.js SDK.


========================================================================
URL: https://app.getdeckle.com/docs/concepts/api-keys
Section: Core concepts
========================================================================

Concepts

# API keys
Secret keys authenticate every request to the Deckle API, SDK, and SMTP relay. Create one per environment, keep it secret, and rotate it when you need to.
Deckle uses secret API keys to authenticate requests. Each key is scoped to a single project and a single environment (Test or Live), so the key you send decides which sandbox — and which data — you touch.
Secret keys only
Deckle does not issue public or publishable keys. Every key starts with sk_live_ or sk_test_ and must stay on your server.

## Creating a key
Keys are managed in the dashboard. You'll see the full key exactly once at creation, so have somewhere safe to paste it before you start.

### Open Developers
In the dashboard top-nav, go to Developers.

### Go to API keys
Open the API keys tab and choose Create key.

### Choose an environment and name
Pick Test or Live, then give the key a descriptive name like production-api or staging. The name is just for you — it helps you tell keys apart later when you rotate or revoke them.

### Copy the key
The full key (sk_live_…) is shown once. Copy it and store it in your secrets manager or environment variables now — you cannot view it again.

## Using a key
Pass the key as a bearer token in the Authorization header on every request, or hand it to the SDK when you construct the client.

```
curl https://app.getdeckle.com/api/v1/emails \
-H "Authorization: Bearer sk_live_..."
```
Store the key in an environment variable such as DECKLE_API_KEY and read it at runtime. The same key also works as your SMTP password — see Keep keys secret below.

## Test vs live keys
Every project has two environments, and the key prefix is what selects between them. A sk_test_ key runs in the sandbox; a sk_live_ key sends to real inboxes. Read Projects & environments for the full model.
PrefixEnvironmentCan send to
sk_test_Test (sandbox)SES simulator mailboxes and your own verified domains only
sk_live_LiveAny recipient, from a verified domain
Test keys are safe to experiment with
A test key can only deliver to AWS SES simulator addresses like success@simulator.amazonses.com or to domains you've verified — it can never reach a real inbox. Campaign and broadcast sends always require a live key.

## Rotating and revoking
Keys don't expire on their own. When one is compromised, when a teammate leaves, or on a routine schedule, rotate it. Because a key is shown only once, rotation is a create-then-swap, not an in-place reset.

### Rotate a key

### Create a replacement
Create a new key in the same environment with a fresh name.

### Deploy the new key
Update DECKLE_API_KEY everywhere it's used and roll out the change.

### Revoke the old key
Once traffic is flowing on the new key, revoke the old one from Developers → API keys.

### Revoke a key
Revoking a key is immediate and permanent — every request using it (API, SDK, or SMTP) then fails with a 401. Revoke any key you no longer need or suspect has leaked.
json
```
{
"error": "Invalid API key"
}
```

## Keep keys secret
Treat a secret key like a password: it can send email from your domain, read your contacts, and trigger campaigns. Keep it on your server and out of anything a browser or a repository can see.
Your key is shown only once
Deckle displays the full key a single time at creation and never stores it in a form we can read back — we keep only a SHA-256 hash of the key plus a masked prefix (like sk_live_…a1b2) so you can recognize it in the dashboard. If you lose the key, you can't recover it — create a new one and revoke the old. This same secret key doubles as your SMTP password, so protect it accordingly.A few rules that keep keys where they belong:
Never ship keys to the clientKeys are server-side only. Don't put them in browser code, mobile apps, or public repos — there are no publishable keys for a reason.

-
- Use environment variablesLoad the key from DECKLE_API_KEY (or your secrets manager) at runtime instead of hardcoding it in source.

## Next steps

-
- Send over HTTPUse your key to send your first email with a raw HTTP request.
Projects & environmentsSee how Test and Live environments and per-project isolation fit together.


========================================================================
URL: https://app.getdeckle.com/docs/concepts/dashboard
Section: Core concepts
========================================================================

Concepts

# The dashboard
A quick tour of the Deckle dashboard — the top-nav, the environment and project switchers, and the shape every list page shares.
The dashboard lives at app.getdeckle.com and is where you verify domains, build templates, manage your audience, and watch what you send. It’s dark-only by design, so every screen is tuned for long sessions in the editor and the campaign report.

## Navigation
The top navigation bar is the same on every page. Six primary destinations sit in the nav itself; account-level settings live behind the account menu on the far right.
Nav itemRouteWhat’s there
Dashboard/Sending overview and KPIs for the current project and environment.
Audience/audienceContacts, events, segments, and suppressions.
Templates/templatesThe template gallery and your saved, branded templates.
Campaigns/campaignsOne-off and scheduled broadcasts, plus their reports.
Automations/automationsVisual, event-driven workflows and their run history.
Developers/developersAPI keys, webhooks, SMTP credentials, and logs.
Account menu
Domains, Settings, Team, and Billing live in the account menu at the top-right, not in the main nav. That’s where you verify a sending domain and invite teammates.

## Environments & projects
Two switchers in the top bar control the scope of everything you see and do. Together they answer a single question: which project, and Test or Live?

### Test / Live toggle
The environment toggle flips the whole dashboard between your Test and Live data. Test is fully sandboxed — sends only reach the AWS SES simulator or your own verified domains — while Live sends to real inboxes. The toggle mirrors the key you use in code: sk_test_ keys read and write Test, sk_live_ keys read and write Live. See Projects & environments for the full model.

### Project switcher
A project is an isolated workspace with its own contacts, templates, domains, API keys, and events. Use the project switcher — right next to the environment toggle — to jump between workspaces or create a new one. Nothing crosses the boundary: switching projects swaps out every list on every page.
Read the top bar first
Before you send a test broadcast or debug a “missing” contact, glance at the top bar. Most surprises come down to being in the wrong project or the wrong environment.

## Anatomy of a page
Every list page in Deckle — Contacts, Templates, Campaigns, Automations — follows the same three-part layout, so once you know one, you know them all.

- Header & KPI cards. The page title sits above a row of KPI cards that summarize the current view — total contacts, delivery rate, active automations — scoped to your selected project and environment.
- Search, filter & action. A control row below the header holds search, tabs or filters, and the primary action button (for example, New campaign or Import contacts) on the right.
- Table. The main content is a table of records. Rows link to a detail view — a contact’s activity timeline, a campaign’s report, or a template in the editor.Because the pattern is consistent, the primary action is always where you expect it and the KPIs always reflect the same scope as the table beneath them.

## Next steps
API keysCreate Test and Live keys in Developers, and learn how they map to environments.
ContactsBuild your audience — the records behind the Audience section and its timelines.


========================================================================
URL: https://app.getdeckle.com/docs/mcp
Section: Build with AI
========================================================================

Build with AI

# Model Context Protocol (MCP)
Connect Claude, Cursor, and other AI tools to Deckle so they can manage your email — send messages, build templates and campaigns, edit automations, and manage contacts — straight from chat.
Deckle ships a remote MCP server. Point any MCP-capable AI tool at it with your secret key and it can drive your project through the same v1 API — with the same auth, validation, scoping, and rate limits.

## The server
POSThttps://app.getdeckle.com/mcpIt speaks JSON-RPC over Streamable HTTP and authenticates with a Deckle secret API key in the Authorization header — exactly like the REST API. Every tool call is scoped to the key’s project and environment.
Your config holds a secret
The key in your MCP config can send email and manage your data. Keep the file private, and use a sk_test_ key while you experiment.

## Connect your tool
Get a key from Developers → API keys, replace YOUR_SECRET_KEY below, and add the config for your client. They all point at the same URL and differ only in file format.

```
claude mcp add --transport http deckle https://app.getdeckle.com/mcp \
--header "Authorization: Bearer YOUR_SECRET_KEY"
```
You can also connect from the dashboard: Developers → Connect AI has a copy-paste recipe for each tool.
No remote-MCP support?
If your client can’t send an Authorization header on a remote server, bridge through the mcp-remote stdio proxy:bash
```
npx -y mcp-remote https://app.getdeckle.com/mcp \
--header "Authorization: Bearer YOUR_SECRET_KEY"
```

## What the AI can do
The server exposes tools across every core resource:
AreaTools
EmailsSend transactional email, list sent emails, check a message’s status.
TemplatesList, read, create, and edit templates (blocks or raw HTML).
CampaignsList, read, create, update, and send campaigns.
AutomationsList, read, create, update, and delete automations.
ContactsList, read, upsert, update, and delete contacts.
EventsRecord custom events for a contact.
SuppressionsList, add, and remove suppressed addresses.
Test it
After connecting, try asking your assistant: “Using Deckle, create a welcome template and send a test to me@example.com.” It will call the tools for you.

## Set it up in three steps

### Create a secret key
In Developers → API keys, create a key (start with Test) and copy it.

### Add the server to your tool
Paste the config above for your client, swapping in your key, and restart the tool.

### Ask it to do something
Deckle’s tools now appear to your assistant. Ask it to draft a campaign or send an email and confirm the result in the dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/sending/sdk
Section: Sending email
========================================================================

Sending

# Send with the SDK
Send transactional and marketing email from your own verified domain with the official @deckle/sdk Node client.
The Deckle SDK is a thin, zero-dependency wrapper over the REST API. Create a client with your secret key, then call deckle.emails.send() — no request-signing or boilerplate to write. It runs on Node 18+, Deno, Bun, and the browser.

## Install
Add the SDK to your project. It ships with TypeScript types and has no runtime dependencies.
bash
```
npm install @deckle/sdk
```
Grab a secret key from the dashboard under Developers → API keys and store it in your environment as DECKLE_API_KEY. Use an sk_test_ key while you build and an sk_live_ key in production — see API keys for the difference.

## Send an email
Instantiate the client once and reuse it. The from address must belong to a domain you have verified, and either html or text (or a template) is required. The call returns the email's id and current status.

```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

const email = await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Welcome to Acme 👋",
html: "<h1>Hey Jane</h1><p>Thanks for joining.</p>",
});

console.log(email.id); // "email_9f2c…"
```
You can pass an array to to for multiple recipients, and add cc, bcc, reply_to, and attachments the same way. Raw html sends go out as-is; for open and click tracking, send with a template instead.
Your from-domain must be verified
Deckle only delivers from domains you own and have verified (Model A). If the domain in from is not verified, the send is rejected. Add and verify a domain under Domains before sending to real inboxes. Test keys can only send to your verified domains or the AWS SES simulator mailboxes.

## Send with a template
Pass a template id instead of html to render one of your stored templates. Fill its {{variable}} placeholders with the variables object — values also merge with the contact's stored data — and Deckle injects open-pixel and click tracking automatically. You can override the subject per send.
send-template.ts
```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

const email = await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Your Acme receipt", // optional override
template: "tmpl_receipt",
variables: {
first_name: "Jane",
order_id: "ord_1234",
total: "$49.00",
},
});
```
See Variables & personalization for placeholder and fallback syntax like {{first_name | "there"}}.

## Inspect sent email
Look up a single email by id, or page through everything you've sent. List results are cursor-based — pass next_cursor back as cursor while has_more is true.
inspect.ts
```
// Fetch one email
const email = await deckle.emails.get("email_9f2c…");
console.log(email.status); // "delivered"

// List recent emails, filtered by status
const page = await deckle.emails.list({
status: "bounced",
limit: 50,
});

for (const item of page.data) {
console.log(item.id, item.status);
}

if (page.has_more) {
const next = await deckle.emails.list({
status: "bounced",
cursor: page.next_cursor!,
});
}
```
For richer delivery signals — bounces, complaints, opens, and clicks in real time — subscribe to webhooks rather than polling list.

## Handling errors
Every failed request throws a DeckleError. It carries the HTTP status, a human-readable message, and the parsed response body. Wrap sends in a try/catch and branch on the status.
errors.ts
```
import { Deckle, DeckleError } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

try {
await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Welcome to Acme 👋",
html: "<h1>Hey Jane</h1>",
});
} catch (err) {
if (err instanceof DeckleError) {
// err.status → HTTP status code (e.g. 422, 429)
// err.message → "message" from { "error": "..." }
// err.body → the parsed error response
if (err.status === 429) {
console.warn("Rate limited — retry after a moment");
} else if (err.status === 422) {
console.error("Rejected:", err.message);
} else {
throw err;
}
} else {
throw err;
}
}
```
Common statuses: 422 for a rejected send (unverified domain, suppressed recipient, or missing field), 401 for an invalid key, and 429 when you exceed 120 requests / minute — the response includes a Retry-After header. See Errors for the full list.

## Next steps
Send with templatesRender branded, tracked emails from your stored templates.
IdempotencySafely retry sends without delivering the same email twice.
Emails API referenceEvery field and response for send, get, and list.


========================================================================
URL: https://app.getdeckle.com/docs/sending/http
Section: Sending email
========================================================================

Sending

# Send over HTTP
Send email with a single authenticated POST request — no SDK required. Works from any language or runtime that can make an HTTP call.
The @deckle/sdk is just a thin wrapper around one endpoint. If you’d rather call the API directly — from a language we don’t ship an SDK for, or from a shell script — everything you need is a Bearer token and a JSON body.

## The endpoint
All sends go through a single endpoint. Send a POST request with your JSON body and authenticate with your secret API key in the Authorization header.
POST/api/v1/sendhttp
```
POST https://app.getdeckle.com/api/v1/send
Authorization: Bearer sk_live_...
Content-Type: application/json
```
The base URL is https://app.getdeckle.com/api/v1. Create a key in the dashboard under Developers → API keys — the full sk_live_... value is shown once at creation, so store it somewhere safe. See API keys for details.
Test vs. live keys
A sk_test_ key can only send to the AWS SES simulator (for example success@simulator.amazonses.com) or your own verified domains. Swap in a sk_live_ key to reach real inboxes.

## Send a request
The body is JSON with snake_case fields. to, from, and subject are required, plus either html or template. The from address must be on a domain you’ve verified.

```
curl -X POST https://app.getdeckle.com/api/v1/send \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <hello@acme.com>",
"to": "jane@example.com",
"subject": "Welcome to Acme 👋",
"html": "<h1>Hey Jane</h1><p>Thanks for joining.</p>"
}'
```
You can pass cc, bcc, reply_to (a string or array), a plain-text text alternative, and attachments in the same body. For the full field list, see the emails API reference.

## The response
A successful send returns 200 with a JSON object describing the queued email. The id is Deckle’s email log id (prefixed email_) — use it to look up status later.
json
```
{
"id": "email_2Nc8Kx1mQvRz",
"status": "queued",
"messageId": "0100019200000000-11111111-2222-3333-4444-555555555555-000000@eu-west-1.amazonses.com"
}
```
Not sending yet?
If your project doesn’t have delivery configured, the request returns 202 and the email is accepted and queued rather than sent immediately. Verify a domain to start delivering.

## Using a template
Instead of raw html, pass a template id and a variables object. Deckle renders the stored template with your values, injects a plain-text alternative, and — unlike raw HTML sends — automatically adds open and click tracking.
json
```
{
"from": "Acme <hello@acme.com>",
"to": "jane@example.com",
"subject": "Your Acme receipt",
"template": "tmpl_welcome",
"variables": {
"first_name": "Jane",
"plan": "Pro"
}
}
```
Placeholders in the template use {{variable}} syntax, with an optional fallback like {{first_name | "there"}}. The subject can be overridden per send, as shown above. See Templates and Variables & personalization for more.

## Errors
Errors return the appropriate HTTP status and a JSON body of the shape { "error": "message" }. The most common ones:
StatusMeaning
401Missing or invalid API key. Check the Authorization header and that the key hasn’t been revoked.
422The request was understood but couldn’t be processed — a missing required field, an unverified from domain, or a suppressed recipient.
429Rate limited. You’ve exceeded 120 requests per minute for this project; retry after the number of seconds in the Retry-After header.
Idempotent sends
Add an Idempotency-Key header to safely retry a send. A repeat with the same key returns the first result with idempotent: true instead of sending again. See Idempotency.

## Next steps
Use the Node SDKSkip the raw HTTP and send with typed methods and helpers.
Emails API referenceEvery field, response, and status value for the send endpoint.


========================================================================
URL: https://app.getdeckle.com/docs/sending/smtp
Section: Sending email
========================================================================

Sending

# Send over SMTP
Point any SMTP client at Deckle to send email through your verified domain — no SDK or HTTP integration required.
If your framework or platform already speaks SMTP, you can send through Deckle without touching the API. Use your secret API key as the SMTP password and every message routes through your verified domain on AWS SES, just like an API send.

## Credentials
Connect your client with the settings below. The username is always the literal string apikey — the value that matters is the password, which is one of your secret API keys.
SettingValue
Hostsmtp.getdeckle.com
Port587 (STARTTLS) or 465 (TLS)
Usernameapikey
PasswordYour secret API key (sk_live_… or sk_test_…)
Which port?
Prefer 587 with STARTTLS. Use 465 (implicit TLS) if your client or network blocks 587. Both are encrypted.Create a key in the dashboard under Developers → API keys. The same secret key doubles as your SMTP password, so a key with the right environment is all you need. See API keys for how keys map to Test and Live.

## Send with Nodemailer
Here’s a complete example using Nodemailer in Node.js. Store your key in an environment variable rather than hard-coding it.
send-smtp.ts
```
import nodemailer from "nodemailer";

const transporter = nodemailer.createTransport({
host: "smtp.getdeckle.com",
port: 587,
secure: false, // true for port 465
auth: {
user: "apikey",
pass: process.env.DECKLE_API_KEY!,
},
});

await transporter.sendMail({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Welcome to Acme 👋",
html: "<h1>Hey Jane</h1><p>Thanks for joining.</p>",
text: "Hey Jane — thanks for joining.",
});
```
Match the port to the transport
Set secure: false for port 587 (STARTTLS) and secure: true for port 465 (implicit TLS). Mismatching them is the most common connection failure.

## Other frameworks
Any tool that can send over SMTP works with Deckle — point it at the credentials above and send. A few common setups:

### WordPress
Install an SMTP plugin (for example WP Mail SMTP), then set the host to smtp.getdeckle.com, port 587 with encryption/STARTTLS, username apikey, and paste your secret key as the password. Set the “From” address to an address on your verified domain.

### Laravel
Configure the SMTP mailer in your .env:
.env
```
MAIL_MAILER=smtp
MAIL_HOST=smtp.getdeckle.com
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=sk_live_...
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=hello@acme.com
MAIL_FROM_NAME="Acme"
```

### Any other SMTP client
Django, Rails Action Mailer, Postfix, a printer, a CI job — whatever sends mail, give it the host smtp.getdeckle.com, port 587 or 465, username apikey, and your secret API key as the password. There’s nothing Deckle-specific beyond these settings.

## Requirements

- Your from-domain must be verified. The address in the From header has to belong to a domain you’ve added and verified in Domains. Sends from an unverified domain are rejected.
- A live key sends to real inboxes. Use an sk_live_… key for production traffic. A test key (sk_test_…) is sandboxed — it can only reach the AWS SES simulator mailboxes or your own verified domains, never arbitrary recipients.Keep your key secret
Your SMTP password is a full-access API key. Load it from an environment variable or secret store, never commit it, and rotate it by creating a new key and revoking the old one.

## Next steps
API keysCreate, scope, and rotate the secret keys you use as your SMTP password.
Domains overviewAdd and verify the domain you'll send from with DKIM, SPF, and DMARC.


========================================================================
URL: https://app.getdeckle.com/docs/sending/templates
Section: Sending email
========================================================================

Sending

# Templates
Store a design once, then send it by id with per-send variables instead of shipping raw HTML on every call.
A template bundles a reusable subject and design into a single object you reference by id. Send with template instead of html, pass in the values that change, and Deckle renders and instruments the email for you.

## What is a template
A template is a stored, reusable email design — a subject and a body — that lives in your project and is identified by a tmpl_ id. Instead of building the same HTML in your code for every send, you author the design once (in the dashboard or the gallery) and reference it by id at send time.
The stored source uses {{variable}} placeholders, so a single template covers every recipient. You supply the values that differ per send, and Deckle renders the final HTML and a plain-text alternative before delivering through your verified domain.
Templates vs. raw HTML
Reach for a template when the same design is sent repeatedly (receipts, welcome emails, password resets). Send raw html for one-off or fully dynamic content you assemble in code.

## Send with a template
Pass the template id as template and a variables object with the values to fill in. You can override the stored subject per send with the subject field, or omit it to use the template's own subject.

```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
template: "tmpl_welcome",
variables: {
first_name: "Jane",
company: "Acme",
},
});
```
Exactly one of html or template is required. Everything else about the send — cc, bcc, reply_to, and attachments — works the same as a raw HTTP or SDK send.

## Variables
Templates and subjects use {{variable}} placeholders, filled from the variables object on the send and from the contact's stored data. Missing values can fall back with {{first_name | "there"}}.
See Variables & personalization for the full syntax, fallbacks, and conditional blocks.

## Automatic tracking
Template sends are instrumented
When you send with a template, Deckle automatically injects an open-tracking pixel and rewrites links for click tracking, so opens and clicks flow into the contact timeline and your webhooks. Raw html sends are delivered as-is and are not instrumented.If you need open and click analytics on content you build yourself, send it through a stored template rather than inline html. The tracked events surface on the contact timeline and as email.opened and email.clicked webhook events.

## Managing templates
Create, edit, and preview templates in the dashboard under Templates. The editor gives you desktop and mobile previews, light and dark inbox modes, sample variable data, and checks for spam score, broken links, and missing variables.
You can also manage templates programmatically. See the Templates API reference for creating and listing templates, or start from a ready-made design in the template gallery.

## Next steps

-
- VariablesPersonalize subjects and templates with placeholders, fallbacks, and conditionals.
Template galleryDozens of clean, brandable React Email templates to start from.
Templates APICreate, list, and fetch templates over the REST API.


========================================================================
URL: https://app.getdeckle.com/docs/sending/variables
Section: Sending email
========================================================================

Sending

# Variables & personalization
Insert per-recipient values into subjects and templates with {{variable}} placeholders, with fallbacks and conditional blocks for the tricky cases.
Personalization in Deckle is a single primitive: {{variable}} placeholders. Drop them into a subject line or a template, provide values on send or from the contact, and Deckle fills them in as it renders each email.

## Placeholders
A placeholder is a name wrapped in double curly braces, like {{first_name}}. You can use placeholders in the subject and anywhere in a template body. When Deckle renders the email, each placeholder is replaced with the matching value for that recipient.
template.json
```
{
"subject": "{{first_name}}, your order is on its way",
"body": "Hi {{first_name}}, order #{{order_id}} shipped to {{city}} today."
}
```
Placeholder names are case-sensitive and should be lowercase with underscores (first_name, order_id). A placeholder with no matching value renders as empty unless you give it a fallback.
Where variables are applied
Placeholders are resolved for template sends and for the subject line. Raw html sends are delivered as-is and are not instrumented or interpolated — pass a template when you want personalization.

## Providing values
Values come from two places, merged together for each recipient:
Value sources
variablesobjectOptionalA key/value map you pass on the send call. Great for one-off values that only exist at send time, like order_id or a magic link.contact.dataobjectOptionalThe custom data stored on a contact (keyed by email). Anything you saved on the contact is available as a placeholder without repeating it on every send.Pass a variables map alongside the template when you send. Keys match placeholder names; values are strings (or numbers that render as text).

```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
template: "tmpl_shipping_update",
variables: {
first_name: "Jane",
order_id: "1234",
city: "Portland",
},
});
```
When you send to a known contact, Deckle also pulls from that contact's stored data. If a placeholder appears in both places, the variables you pass on the send win — so you can store defaults on the contact and override them per send.
contact.ts
```
// Store data on the contact once...
await deckle.contacts.create({
email: "jane@example.com",
name: "Jane Doe",
data: { first_name: "Jane", plan: "Pro" },
});

// ...then {{first_name}} and {{plan}} resolve automatically,
// even when you don't pass them in variables.
await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
template: "tmpl_welcome",
});
```
Precedence at a glance
Send-time variables override contact.data, which overrides the placeholder’s fallback, which falls back to empty. Most specific wins.

## Fallback values
Real data is never complete. Give any placeholder a fallback with the pipe syntax so a missing value degrades gracefully instead of leaving a hole:
text
```
Hi {{first_name | "there"}}, welcome aboard.
```
If first_name resolves to a value, that value is used; otherwise the quoted fallback is rendered. Fallbacks work everywhere placeholders do — subject and body alike.
PlaceholderValue presentValue missing
{{first_name}}Jane(empty)
{{first_name | "there"}}Janethere
Default your greetings
A fallback on the first placeholder in a greeting is the single highest-leverage habit for personalization — Hi {{first_name | "there"}} never renders an awkward “Hi ,”.

## Conditional blocks
For advanced templates you can render a chunk of content only when a value is present. This is useful when a section only makes sense for some recipients — a plan name, a referral code, a shipping note.
text
```
{{#if plan}}
You're on the {{plan}} plan — thanks for being a customer.
{{else}}
Upgrade any time to unlock more sends.
{{/if}}
```
Conditional blocks are an advanced feature; for most emails, placeholders with fallbacks cover what you need. Build and preview conditionals in the template editor before you rely on them in a send.

## Previewing
The template editor renders your placeholders against sample data so you can see exactly how a personalized email will look before it goes out.

### Open the template
In the dashboard, go to Templates and open the template you're editing.

### Fill in sample data
Set sample values for each placeholder in the editor's variable panel. Try both a filled value and an empty one to confirm your fallbacks behave.

### Preview across inboxes
Toggle desktop/mobile and light/dark inbox preview. The editor also flags missing variables and broken links so nothing ships half-personalized.Preview is not a send
Sample data lives in the editor only. Actual sends resolve placeholders from your send-time variables and the recipient contact’s stored data — not from the preview panel.

## Next steps
TemplatesCreate reusable templates, then send them with a template id and variables.
ContactsStore per-contact data so placeholders resolve automatically on every send.


========================================================================
URL: https://app.getdeckle.com/docs/sending/attachments
Section: Sending email
========================================================================

Sending

# Attachments
Attach files — PDFs, images, CSVs, or anything else — to a transactional email by passing them as base64-encoded content.
Add an attachments array to any send. Each item carries a filename and the file’s bytes as a base64-encoded string, and Deckle delivers it alongside your email from your verified domain.

## The shape
Each entry in the attachments array is an object with the following fields.
Attachment fields
filenamestringRequiredThe name the file is delivered as, including its extension — for example invoice.pdf.contentstring (base64)RequiredThe file’s bytes, base64-encoded. Items without content are dropped.content_typestringOptionalThe MIME type, such as application/pdf or image/png. Optional — Deckle infers a sensible type from the filename when omitted.

## Example
Read a file, base64-encode it, and pass it in attachments. The SDK takes the same fields as the raw JSON body.

```
import { readFileSync } from "node:fs";
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

const invoice = readFileSync("./invoice.pdf");

await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Your invoice",
html: "<p>Thanks for your order — your invoice is attached.</p>",
attachments: [
{
filename: "invoice.pdf",
content: invoice.toString("base64"),
content_type: "application/pdf",
},
],
});
```

## Notes
A few things to keep in mind when attaching files:
Behavior
Base64-encode contentrequiredOptionalcontent must be a base64 string, not raw bytes or a file path. In Node, buffer.toString("base64") does the job.Empty items are droppedbehaviorOptionalAny attachment whose content is missing or empty is silently skipped, so the email still sends without it.Keep sizes reasonableguidanceOptionalLarge attachments hurt deliverability and can be rejected by receiving servers. Prefer a link to a hosted file for anything sizable, and reserve attachments for small documents.Link instead of attach when you can
For big files or ones a recipient may not expect, sending a link keeps your message light and your deliverability healthy. Reserve attachments for small, expected documents like receipts and invoices.

## Next steps
Send with the SDKEvery send option — templates, variables, cc/bcc, and idempotency.
Emails API referenceThe full request and response schema for sending email over HTTP.


========================================================================
URL: https://app.getdeckle.com/docs/sending/idempotency
Section: Sending email
========================================================================

Sending

# Idempotency
Retry a send safely. An idempotency key guarantees a given request runs at most once, so a dropped connection or a retry loop never turns into a double-send.
Networks fail in the worst places — right after your request reaches Deckle but before the response reaches you. Instead of guessing whether the email went out, attach an idempotency key and retry with confidence: the second call returns the first result rather than sending again.

## Why idempotency
A POST /v1/send that times out is ambiguous. Maybe the email sent and you lost the response; maybe it never arrived. Without a safeguard, retrying risks sending the same message twice, and skipping the retry risks not sending at all.
An idempotency key removes the ambiguity. You generate one stable key per logical send and pass it on every attempt. Deckle records the first request under that key and, for any repeat, replays the original response. That gives you:

- Safe retries. Retry a timed-out or failed request as many times as you need — only the first one actually sends.
- No double-sends. A duplicated webhook, a double-clicked button, or an at-least-once job runner can all fire the same send twice without reaching your recipient twice.

## The Idempotency-Key
Send the key in the Idempotency-Key request header on POST /v1/send. With the SDK, pass idempotencyKey on the send call and the header is set for you.

```
curl -X POST https://app.getdeckle.com/api/v1/send \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_1234" \
-d '{
"from": "Acme <hello@acme.com>",
"to": "jane@example.com",
"subject": "Your receipt",
"html": "<h1>Thanks for your order</h1>"
}'
```
Where it applies
The Idempotency-Key header is honored on POST /v1/send. Scope it to the transactional sends you retry — receipts, magic links, and alerts.

## Behavior
The first request with a given key runs normally and Deckle stores its result. Any later request that reuses the same key skips sending entirely and returns that stored result, with an extra idempotent: true field so you can tell a replay from an original.

```
{
"id": "email_9f2c...",
"status": "queued",
"messageId": "0100018e..."
}
```
The repeat returns the same id and messageId as the original — it points at the one email that was already created. Nothing new is sent.
ScenarioWhat happens
First request with a keySends normally; result is stored under the key.
Repeat with the same keyReturns the first result with idempotent: true; does not resend.
Different key (or no key)Treated as a brand-new send.
Same key, different body
A key identifies one logical send. If you reuse a key but change the payload, you still get the original result back — Deckle does not re-evaluate the new body. Use a fresh key when you genuinely mean to send something different.

## Choosing a key
Derive the key from a stable business identifier that maps one-to-one to the email you intend to send — the order id, the invoice number, the password-reset token. That way every retry of the same logical event naturally produces the same key.

- Do use a deterministic id like order_1234, invoice_2026_0042, or reset_{userId}_{tokenId}.
- Don't use a random value generated fresh on each attempt — a new UUID per retry defeats the purpose, since every call looks unique.If a single business event legitimately triggers several distinct emails, give each one its own key by adding a suffix — for example order_1234_receipt and order_1234_shipping.
Keys are per project
Idempotency keys are scoped to your project, so keys from different projects never collide. A short, human-readable key also makes retries easy to trace in your own logs.

## Next steps
Idempotency (API reference)The header, response fields, and semantics in the REST reference.
Send with the SDKSend transactional email from Node with the @deckle/sdk client.


========================================================================
URL: https://app.getdeckle.com/docs/audience/contacts
Section: Audience
========================================================================

Audience

# Contacts
A contact is a person on your list, keyed by email. Store names and arbitrary custom data, then use contacts to power segments, campaigns, and automations.
Everything in your audience is built around the contact. It's just an email plus whatever you want to know about the person behind it — and it's the anchor that ties events, sends, and automations together.

## The contact model
Contacts are keyed by their email address, which is unique within a project. A contact carries a small set of built-in fields plus a free-form data object for anything specific to your product.
Contact fields
emailstringRequiredThe contact's email address and unique key within the project.namestringOptionalOptional display name, used for {{first_name}} and other personalization.subscribedbooleanOptionalWhether the contact is subscribed to marketing email. Defaults to true. Unsubscribing (or a complaint) flips this to false.sourcestringOptionalWhere the contact came from, e.g. api, import, or a value you set yourself.dataobjectOptionalArbitrary JSON — any custom fields you want to store on the contact.Unlimited contacts
There's no cap on how many contacts you store, and no per-contact fee. Deckle bills on what you send, not on the size of your list — so you can keep every address, subscribed or not.

## Create or update
Contacts are upserted by email: create a contact that already exists and Deckle updates it instead of erroring. The response status tells you which happened — 201 when a new contact was created, 200 when an existing one was updated.

```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

const contact = await deckle.contacts.create({
email: "jane@example.com",
name: "Jane Doe",
subscribed: true,
source: "signup-form",
data: {
plan: "pro",
company: "Example Inc.",
},
});

// contact.id -> "contact_..."
```
Upsert semantics
Because create is an upsert on email, it's safe to call on every signup or sync — you won't create duplicates. Only the fields you pass are changed; omitted fields keep their previous values.

## List, get, update, delete
The full set of contact operations is available from the SDK and the REST API. Listing is cursor-based — pass limit and cursor to page through results.
contacts.ts
```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

// List (cursor-based pagination)
const { data, has_more, next_cursor } = await deckle.contacts.list({
limit: 50,
});

// Get a single contact by id or email
const contact = await deckle.contacts.get("jane@example.com");

// Update — merge in new fields
await deckle.contacts.update("jane@example.com", {
data: { plan: "enterprise" },
});

// Delete
await deckle.contacts.delete("jane@example.com");
```
Prefer to work over HTTP directly? Each operation maps to a REST endpoint — see the Contacts API reference for request and response shapes.

## Custom data
The data object holds arbitrary JSON. Store plan tiers, company names, feature flags, lifecycle stages — whatever your product cares about. There's no schema to define up front; just send the keys you want.
json
```
{
"plan": "pro",
"company": "Example Inc.",
"signup_date": "2026-05-01",
"trial_ends": "2026-05-15",
"seats": 12,
"beta_features": ["reports", "automations"]
}
```
Custom data is what makes the rest of the platform expressive. It feeds {{variable}} personalization in templates and subject lines, and it's available as attributes when you build segments and branch inside automations.
Personalize with data
Any key on data can be referenced in a template with a fallback, e.g. {{plan | "free"}}. See Variables & personalization for the full syntax.

## Import & export
Already have a list elsewhere? Import it from the dashboard, or add contacts one at a time through the API. You can export at any time.

### Open Audience → Contacts
In the dashboard top-nav, go to Audience and open the Contacts table. Choose Import.

### Upload your CSV
Drop in a CSV file. The first row should be your column headers.

### Map your fields
Match each CSV column to a contact field — email, name, subscribed — or map it into data as a custom field. Rows are upserted by email, so re-importing updates existing contacts rather than duplicating them.

### Export when you need to
Use Export on the Contacts table to download your list as a CSV, including custom data fields.

## Automations
Contacts don't just sit in a table — they trigger workflows. When a new contact is created as subscribed, Deckle looks for live automations that fire on the contact.subscribed trigger and enrolls the contact automatically.
Auto-enroll on subscribe
Newly-created subscribed contacts are automatically enrolled in any live welcome automation triggered by contact.subscribed. Draft automations don't enroll anyone — set an automation to live to start welcoming new contacts.The contact detail page also shows an activity timeline — sends, opens, clicks, and events — so you can see a contact's full history in one place.

### Reasons a contact might not be subscribed
A contact's subscribed flag flips to false in a few cases:
CauseEffect
Unsubscribe (one-click or hosted page)Contact is unsubscribed and added to suppressions
Complaint (marked as spam)Auto-suppressed via SES/SNS; no further marketing email
Imported with subscribed: falseStored, but excluded from marketing sends and auto-enroll

## Next steps
EventsRecord what contacts do and use those actions to trigger automations.
SegmentsBuild live, rule-based groups over contact attributes and events.
Contacts APIEvery contact endpoint, parameter, and response for the REST API.


========================================================================
URL: https://app.getdeckle.com/docs/audience/events
Section: Audience
========================================================================

Audience

# Events
Record what your users do as named events, tie them to a contact by email, and use them to trigger automations.
Events are the heartbeat of Deckle’s event-driven core. Every time something meaningful happens in your product, send an event — Deckle attaches it to the matching contact, adds it to their timeline, and lets your automations react in real time.

## What are events
An event is a named action tied to a contact by their email address. The name describes what happened, and you can attach an optional data payload with details about the action. Deckle doesn’t prescribe a taxonomy — you choose names that map to your product.
A common convention is object.action, lowercase and dot-separated:
Event nameFires when
user.signed_upA new user creates an account.
order.completedA customer finishes a purchase.
trial.expiredA free trial reaches its end date.
Events show up on the contact’s activity timeline alongside sends, opens, and clicks, so you get one view of everything a person has done.

## Track an event
Send an event with POST /v1/events or the SDK’s events.create. A name is required; email links the event to a contact, and data carries any structured details you want on the timeline and available to automations.

```
curl -X POST https://app.getdeckle.com/api/v1/events \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "order.completed",
"email": "jane@example.com",
"data": {
"order_id": "ord_1234",
"total": 4200,
"currency": "usd"
}
}'
```
Body parameters
namestringRequiredThe event name, e.g. user.signed_up. Use a stable, lowercase convention so your automation triggers stay consistent.emailstringOptionalThe contact this event belongs to. Used to match an existing contact; if omitted or unknown, the event is still recorded with contact_id set to null.dataobjectOptionalOptional structured payload with details about the action. Stored with the event and available to automation conditions.

## Linking to contacts
Deckle matches an event to a contact by its email. When the address belongs to an existing contact, the event is attached to them and appears on their timeline immediately.
Unknown emails are never dropped. If no contact matches — or you send an event without an email at all — the event is still recorded with contact_id set to null. This means you can start emitting events before a person becomes a contact, and the history is already there once they are.
Emails are the key
Contacts are keyed by email across all of Deckle. Send events with the same address you use when you create a contact, and everything lines up on one timeline.

## Powering automations
Events are what make automations event-driven. An automation can use a custom event as its trigger, so posting order.completed can start a post-purchase flow the moment it happens.
Events also wake automations that are waiting. A wait step pauses an enrollment until a specific event arrives (or a timeout elapses) — for example, wait for order.completed after a “complete your setup” nudge, and continue the moment the user follows through.
Data drives conditions
Automation condition steps can branch on the event’s data, so a single order.completed event can route high-value orders differently from the rest.

## Next steps
AutomationsTrigger multi-step flows from events and wake waits when they arrive.
Events API referenceThe full request and response schema for tracking events.


========================================================================
URL: https://app.getdeckle.com/docs/audience/segments
Section: Audience
========================================================================

Audience

# Segments
Live, rule-based groups of contacts that recalculate as your audience changes — target them from campaigns and reference them by id in the API.
A segment is a saved set of rules over your contacts. Instead of exporting a static list, you describe who belongs — subscribed contacts who fired order.completed in the last 30 days, say — and Deckle keeps the membership up to date for you.

## What is a segment
A segment is a live, rule-based group of contacts. You define the rules once; Deckle evaluates them continuously against your audience. A contact is a member whenever they match the rules and drops out the moment they stop matching — you never maintain the list by hand.
Segments are the marketing counterpart to your event-driven core: contacts are keyed by email, events record what they do, and a segment turns those attributes and events into a targetable audience for a campaign.
Managed in the dashboard
Segments are created and edited in the dashboard under Audience → Segments. There is no public write endpoint — you can’t create or update a segment over the API. You reference an existing segment by its id where a campaign accepts a segment.

## Rules
A segment is built from rules, combined into AND / OR groups. Within a group you choose whether a contact must match every rule (AND) or any rule (OR), and you can nest groups to express more precise audiences. Each rule targets one of four categories.
Rule typeMatches onExample
attributeA contact field or custom key in the contact’s stored datadata.plan is pro
eventWhether a named event was recorded for the contactfired order.completed at least once
engagementSend activity — opens and clicks on your emailopened an email in the last 30 days
subscribedThe contact’s subscription statesubscribed is true
A typical segment mixes categories. To reach engaged pro customers, you might combine a subscribed rule, an attribute rule, and an engagement rule inside a single AND group.
segment-rules.json
```
{
"match": "and",
"rules": [
{ "type": "subscribed", "value": true },
{ "type": "attribute", "field": "data.plan", "op": "eq", "value": "pro" },
{
"match": "or",
"rules": [
{ "type": "event", "name": "order.completed", "op": "occurred" },
{ "type": "engagement", "metric": "opened", "within_days": 30 }
]
}
]
}
```
Preview before you send
The segment editor shows an estimated member count and a sample of matching contacts as you add rules, so you can sanity-check the audience before you target it from a campaign.

## Live membership
Segment membership is not a snapshot. Deckle recalculates it as your data changes: when a contact is created or updated, when an event is recorded, and when engagement (an open or click) comes in. A contact enters or leaves the segment automatically based on whether they currently match the rules.

### How a contact moves in and out
Because membership follows your data, ordinary API calls change who belongs — no separate segment call is needed.
What triggers a recalculation
contact changeattribute rulesOptionalUpserting a contact with POST /v1/contacts or updating custom data re-evaluates attribute and subscribed rules for that contact.event recordedevent rulesOptionalPosting an event with POST /v1/events can pull a contact into a segment whose rules require that event.engagementengagement rulesOptionalOpens and clicks reported back from your sends keep engagement-based rules current.For example, recording order.completed for a subscribed pro customer adds them to the segment above on the next evaluation — you only had to send the event.

```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

// Recording this event may move the contact into a segment
// whose rules include order.completed.
await deckle.events.create({
name: "order.completed",
email: "jane@example.com",
data: { order_id: "order_1234", amount: 4900 },
});
```

## Use in campaigns
The main job of a segment is to target a campaign. When you create a campaign you set its target to segment and pass the segment’s id in the segment field. Membership is resolved when the campaign sends, so you reach whoever matches the rules at send time.

### Build the segment in the dashboard
Open Audience → Segments, add your AND/OR rules, and save. Copy the segment’s id (it looks like seg_...) from the segment detail page.

### Target it from a campaign
Create a draft campaign with target: "segment" and segment: "seg_...". The campaign will broadcast only to contacts in that segment.

### Send with a live key
Send the campaign with POST /v1/campaigns/{id}/send using a sk_live_ key. Deckle resolves current membership and delivers to it.
```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

// Reference the segment by id — there is no segment write API.
const campaign = await deckle.campaigns.create({
name: "Pro customer update",
subject: "What's new for Pro",
from_name: "Acme",
from_email: "hello@acme.com",
target: "segment",
segment: "seg_engaged_pro",
});

await deckle.campaigns.send(campaign.id); // live key only
```
Reference by id only
The API reads segments but never writes them. Wherever a campaign accepts a segment, pass the id of a segment you built in the dashboard — you can’t define rules inline.

## Next steps
CampaignsBroadcast to a segment or your whole list, with A/B subject lines and reports.
ContactsCreate and update the contacts and custom data your segment rules match on.


========================================================================
URL: https://app.getdeckle.com/docs/audience/suppressions
Section: Audience
========================================================================

Audience

# Suppressions
The suppression list is a per-project set of email addresses Deckle will never send to. It protects your sender reputation by keeping known-bad and opted-out recipients out of every send.
Every send is checked against the suppression list first. If a recipient is on it, the send is rejected before it ever reaches AWS SES — so a hard bounce or complaint you’ve already seen can’t happen twice.

## What is the suppression list
The suppression list is a project-scoped set of addresses that Deckle refuses to deliver to. It exists to protect your deliverability: repeatedly emailing an address that hard-bounced, or one that marked you as spam, is exactly what damages a sender’s reputation. Because Deckle uses Model A — you send from your own verified domain — that reputation is yours to protect.
Suppression is enforced on every send path: transactional API sends, SMTP, campaigns, and automations. There is no way to opt an individual send out of the check.

## Automatic vs manual
Addresses land on the list two ways. Most entries are added for you, but you can also curate the list by hand.

### Added automatically
When AWS SES reports a hard bounce or a complaint, the notification flows back to Deckle over SNS and the recipient is suppressed automatically. You don’t have to do anything — the address is on the list before you could send to it again. Contacts who unsubscribe are suppressed the same way.

### Added manually
You can add and remove addresses yourself, from the dashboard (Audience → Suppressions) or through the API. Manual entries are useful for addresses you already know are bad, or for honoring an opt-out request that came in over another channel. Removing an address clears it from the list so future sends go through again.
Removing is not always safe
Deleting a hard_bounce or complaint entry lets you send to that address again, but the underlying reason usually still holds. Only remove entries you know are safe to re-engage.

## Manage the list
The SDK exposes list, create, and delete on deckle.suppressions. Listing is cursor-paginated like every other list endpoint.

```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

const { data, has_more, next_cursor } = await deckle.suppressions.list({
limit: 50,
});

for (const entry of data) {
console.log(entry.email, entry.reason);
}
```
Full endpoint reference
For request bodies, response shapes, and status codes, see the Suppressions API reference.

## Reasons
Every entry carries a reason that records how the address got onto the list.
ReasonAdded byWhat it means
hard_bounceAutomaticSES reported a permanent bounce — the mailbox doesn’t exist or rejected mail outright.
complaintAutomaticThe recipient marked a message as spam, reported via an SES feedback loop.
unsubscribeAutomaticThe contact opted out through a one-click unsubscribe or the hosted preference page.
manualYouAdded by hand in the dashboard or through the API.

## Sending is blocked
Any send targeting a suppressed address is rejected with HTTP 422 and the standard error body. The message is never queued and never reaches SES.

```
{
"error": "Recipient jane@example.com is suppressed (hard_bounce)"
}
```
The reasons a send can be blocked at this stage are:

- The recipient is on the suppression list for any reason (hard_bounce, complaint, unsubscribe, or manual).
- To resume sending, remove the address with deckle.suppressions.delete(email) — but only once you know the underlying issue is resolved.Test the check
The AWS SES simulator address bounce@simulator.amazonses.com triggers a hard bounce, which auto-suppresses it. Send to it once with a test key to watch the list update.

## Next steps
DeliverabilityKeep complaint rates low and your sender reputation clean.
Suppressions APIEndpoints, parameters, and responses for managing the list.


========================================================================
URL: https://app.getdeckle.com/docs/marketing/campaigns
Section: Marketing
========================================================================

Marketing

# Campaigns
Broadcast a one-off or scheduled email to your whole list or a segment, with optional A/B subject lines and a full post-send report.
A campaign is a broadcast: a single email you compose once and send to many contacts at once. Unlike a transactional send, a campaign has a target audience, respects the suppression list and one-click unsubscribe, and reports back on how it performed.

## What is a campaign
Campaigns are for the email you send to people, not machines — a newsletter, a product announcement, a promotion. You pick an audience (everyone, or a segment), choose a template and subject, and send it as a one-off or on a schedule.
Every campaign starts life as a draft. Drafts are the only editable state — once a campaign is sent it becomes an immutable record you can report on. Because campaigns are broadcasts to real inboxes, they always go out from a verified domain, include a visible unsubscribe link, and skip any address on your suppression list.
Transactional vs. broadcast
Sending a single receipt or magic link? Use emails.send instead. Campaigns are for reaching a list.

## Create a draft
Create a campaign with campaigns.create. It returns a draft — nothing is sent until you call campaigns.send. Give it a name (for the dashboard), the subject and from identity your recipients will see, the template to render, and a target audience.

```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

const campaign = await deckle.campaigns.create({
name: "July product update",
subject: "What's new in Acme this month",
from_name: "Acme",
from_email: "hello@acme.com",
template: "tmpl_newsletter",
target: "all",
});

console.log(campaign.id); // camp_...
```
Campaign parameters
namestringRequiredInternal label for the campaign, shown in the dashboard. Not visible to recipients.subjectstringRequiredThe subject line recipients see. Supports {{variable}} personalization.from_namestringRequiredDisplay name in the From header, e.g. Acme.from_emailstringRequiredSending address. Its domain must be verified — see /docs/domains/overview.templatestringRequiredThe tmpl_... id to render as the email body.targetstringRequiredWho receives the campaign: "all" or "segment".segmentstringOptionalThe segment id to target. Required when target is "segment".preview_textstringOptionalThe preheader shown after the subject in most inbox previews.variantsarrayOptionalAlternate subject lines for an A/B test — see below.

## Targeting
A campaign’s target decides who receives it. Send to your entire audience, or narrow to a live segment — a rule-based group that recalculates as contacts change. Either way, unsubscribed and suppressed contacts are excluded automatically.

### Send to everyone
ts
```
await deckle.campaigns.create({
name: "Launch announcement",
subject: "We shipped something big",
from_name: "Acme",
from_email: "hello@acme.com",
template: "tmpl_announcement",
target: "all",
});
```

### Send to a segment
Set target to "segment" and pass the segment’s id. Segments have no public write API — build them in the dashboard under Audience → Segments, then reference the id here.
ts
```
await deckle.campaigns.create({
name: "Win-back for lapsed users",
subject: "We miss you",
from_name: "Acme",
from_email: "hello@acme.com",
template: "tmpl_winback",
target: "segment",
segment: "seg_lapsed_30d",
});
```
Membership is live
A segment recalculates as contacts and events change, so the recipient set is resolved at send time — not when you create the draft.

## A/B subject lines
Test which subject line lands better by passing a variants array. The subject you set on the campaign is variant A (the base); each entry in variants is an alternate. You can add up to three alternates — B, C, and D — for four subject lines in total.
ts
```
await deckle.campaigns.create({
name: "July product update",
subject: "What's new in Acme this month", // variant A (base)
from_name: "Acme",
from_email: "hello@acme.com",
template: "tmpl_newsletter",
target: "all",
variants: [
"Your July Acme roundup", // variant B
"3 new things in Acme", // variant C
],
});
```
Only the subject line changes between variants — the from identity, template, and target stay the same. Open and click rates are reported per variant so you can see which subject won.

## Send it
Sending is a separate, deliberate step. Call campaigns.send with the campaign’s id to broadcast the current draft to its target audience.
send-campaign.ts
```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

await deckle.campaigns.send("camp_8f2a1c");
```

### Deckle resolves the audience
The target — all contacts or the segment — is expanded at send time, then filtered against unsubscribes and the suppression list.

### Emails are rendered and delivered
Your template is rendered per recipient (with any {{variable}} personalization), an unsubscribe link and one-click headers are added, and each message is delivered through your verified domain.

### Results stream into the report
As SES reports delivery, opens, clicks, bounces, and complaints, the campaign report fills in.Sending requires a LIVE key
Campaign sends only work with a sk_live_ key. With Redis configured, delivery runs asynchronously on the worker so large lists don’t block your request. Without a worker, sends run synchronously and are capped at 200 recipients.

## Reports
Once a campaign is sent, its report tracks how recipients engaged. Fetch it with campaigns.get, or open the campaign in the dashboard. Metrics update as SES and SNS deliver notifications back to Deckle.
MetricWhat it counts
sendsRecipients the campaign was dispatched to after filtering.
deliveredMessages SES confirmed as delivered to the inbox provider.
opensRecipients who opened the email (tracked via the open pixel).
clicksRecipients who clicked a tracked link in the email.
bouncesMessages that hard- or soft-bounced. Hard bounces are auto-suppressed.
complaintsRecipients who marked the email as spam. These are auto-suppressed too.
unsubscribesRecipients who opted out via the unsubscribe link or one-click header.
Keep complaints low
Bounces and complaints suppress the address automatically. Watch your complaint rate — the deliverability guide covers the thresholds bulk senders need to stay under.

## Next steps
AutomationsGo beyond one-off broadcasts with event-driven, multi-step email flows.
Campaigns API referenceEvery parameter and response for creating, listing, and sending campaigns.


========================================================================
URL: https://app.getdeckle.com/docs/marketing/automations
Section: Marketing
========================================================================

Marketing

# Automations
Build multi-step email workflows that react to what your contacts do — welcome series, onboarding drips, and lifecycle flows that run themselves.
An automation is a trigger plus an ordered set of steps. When something happens — a contact subscribes, or you fire a named event — Deckle enrolls the contact and walks them forward through the flow: sending email, waiting, branching, and updating their record along the way.

## What is an automation
Each automation has a single trigger and a list of steps that form a forward flow (a DAG — steps always point onward, never back). A contact enters at the trigger and moves from one step to the next until the flow ends or a branch sends them down a different path.
Steps run in order. A delay or wait step parks the contact until its time or event arrives, then the flow resumes exactly where it left off. Every enrolled contact keeps its own position, so thousands of people can be at different points in the same automation at once.
Contacts are the unit of enrollment
Automations operate on contacts, keyed by email. A step can send a template, wait, branch on a field, or change the contact’s record — always for the one contact moving through the flow.

## Triggers
A trigger decides who enters the automation and when. There are two kinds.
TriggerFires when
contact.subscribedA contact becomes subscribed — for example a newly created subscribed contact, which auto-enrolls in your live welcome flows.
eventA custom event you fire by name (such as user.signed_up or order.completed) matches the automation’s configured event.
For an event trigger, name the event the automation should listen for. Any event you send with that name enrolls the matching contact. The same event stream can also wake a wait step mid-flow — see below.

## Step types
Steps are the building blocks of the flow. Each step has a type that determines what it does and where the contact goes next.
TypeWhat it does
emailSends a template to the contact. Optionally override the subject line for this step.
delayWaits a fixed amount of time before continuing — delayMinutes from 1 to 525600 (one year).
waitPauses until a named event arrives (waitEvent) or a timeout elapses (waitTimeoutMinutes, 1 to 36000). Whichever comes first resumes the flow.
condition / branchAn if/else test on a field, op, and value. A match routes to nextTrue; otherwise to nextFalse.
actionChanges the contact record: unsubscribe, update-field, add-tag, or remove-tag.
Branches keep the flow moving forward
A condition step splits the path in two but never loops back. Point nextTrue and nextFalse at the steps each side should continue to, and leave one unset to end that branch.

## Build it visually
Most automations start in the dashboard. Open Automations in the top nav to design a flow on a canvas — no code required.

### Create an automation
In the dashboard, open Automations and create a new flow. Give it a name so you can find it later.

### Pick a trigger
Choose contact.subscribed or an event trigger and, for events, type the event name to listen for.

### Add steps
Drop in email, delay, wait, condition, and action steps and connect them into the order you want. Branch lanes show the true and false paths side by side.

### Go live
Switch the status from draft to live to start enrolling contacts. Draft flows never enroll anyone.

## Via the API
You can also define an automation programmatically. Pass a trigger and an ordered array of steps to automations.create. The example below sends a welcome email, waits three days, branches on whether the contact has opened, and tags them accordingly.

```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

const automation = await deckle.automations.create({
name: "Welcome series",
trigger: { type: "contact.subscribed" },
steps: [
{
id: "welcome",
type: "email",
template: "tmpl_welcome",
subjectOverride: "Welcome to Acme 👋",
},
{ id: "wait_3d", type: "delay", delayMinutes: 4320 },
{
id: "check_opened",
type: "condition",
field: "opened",
op: "eq",
value: true,
nextTrue: "tag_engaged",
nextFalse: "nudge",
},
{ id: "tag_engaged", type: "action", action: "add-tag", value: "engaged" },
{ id: "nudge", type: "email", template: "tmpl_nudge" },
],
});
```
A new automation is created as a draft. Manage it with automations.list, automations.get, automations.update, and automations.delete, or see the full API reference.

## Going live
An automation is either draft or live. Draft flows are editable but inert — no one is enrolled and no steps run. Setting the status to live starts enrolling matching contacts.

- Draft — the build state. Change the trigger and steps freely; nothing fires.
- Live — the automation enrolls contacts and, on going live, resumes any enrollments that were paused while it was a draft, so contacts pick up where they left off.Test before you flip it live
Once live, real contacts start moving through the flow and receiving email. Preview each template and double-check delays and branches before changing the status.

## Next steps
EventsFire named events to trigger automations and wake steps waiting on a signal.
Automations APIEvery field for creating, updating, and managing automations over the API.
CampaignsBroadcast one-off and scheduled sends to your whole list or a segment.


========================================================================
URL: https://app.getdeckle.com/docs/marketing/template-gallery
Section: Marketing
========================================================================

Marketing

# Template gallery
A built-in library of high-quality, deliverability-safe email templates you can brand, preview, and export — or send by id straight from the API.
Every Deckle project ships with a gallery of ready-made templates. Pick one, let your brand kit apply automatically, and either send it by id or export the markup. No template starts from a blank canvas.

## A gallery, in the product
Open Templates in the dashboard top-nav to browse dozens of embedded templates authored with React Email. Each one renders to clean, inline-CSS HTML with a plain-text alternative, so it lands well in real inboxes — including the clients that strip <style> tags and ignore modern CSS. The markup is deliverability-safe by construction: table-based layout, inlined styles, no external stylesheets, and no scripts.
From any card you can Use template (adds a branded copy to your project), Preview it against sample data, or Export it as HTML, a React Email component, or a copy to your clipboard. Once a template lives in your project it gets an id like tmpl_9f3c... that you can pass to the send API.
Send by id
Reference a template on a send with template: "tmpl_..." instead of raw html. Template sends are rendered with your variables and automatically get open-pixel and click tracking. See Sending with templates.
```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Welcome to Acme 👋",
template: "tmpl_9f3c2a1b",
variables: { first_name: "Jane" },
});
```

## Categories
The gallery is organized by what the email is for, so you can jump to the shape you need.

- Transactional — receipts, magic links, password resets, and other one-to-one messages triggered by user action.
- Onboarding — welcome emails, getting-started checklists, and setup nudges for new signups.
- Newsletter / Content — long-form content layouts for regular sends to your audience.
- Product — feature announcements, changelog digests, and release notes.
- Lifecycle / Marketing — re-engagement, win-back, upgrade, and promotional campaigns.
- Utility — plain, structural layouts to start from when you want minimal styling.

## Branding
Set your project’s brand kit once and every gallery template inherits it. That’s how a single template design fits many brands: the layout stays fixed while your colors, type, logo, and footer flow in automatically.
Brand elementApplies to
ColorsButtons, links, accents, and dividers throughout the template.
FontHeadings and body text, with email-safe fallbacks for older clients.
LogoThe header lockup at the top of the email.
FooterYour address, links, and the required unsubscribe line.
Footer and compliance
The template footer includes a visible unsubscribe link, and marketing sends add the List-Unsubscribe headers required by bulk-sender rules. See Unsubscribes.

## Editor & preview
Every template opens in an editor built for catching problems before you send. Preview a template the way recipients will actually see it:

- Desktop and mobile — switch viewports to check that the layout reflows.
- Light and dark inbox — preview against both inbox color schemes.
- Sample-data variables — fill {{variable}} placeholders with sample values to see the rendered result, including {{first_name | "there"}} fallbacks.Templates use the same {{variable}} syntax as the rest of Deckle, filled from the variables you pass on send and the contact’s stored data. Learn the full syntax in Variables & personalization.

## Export
You don’t have to send through the gallery to use it. Export any template in the format that fits your workflow:

### Export as HTML
Get the fully rendered, inline-CSS HTML — ready to drop into a raw html send, another system, or version control.

### Export as React Email
Get the template as a React Email component you can commit to your codebase and render yourself.

### Copy
Copy the current output straight to your clipboard for a quick paste.Raw HTML isn't instrumented
Exported HTML sent with the html field is delivered as-is — Deckle does not inject open or click tracking into raw HTML. Send by template id if you want opens and clicks tracked automatically.A minimal template send looks the same whether the markup came from the gallery or your own React Email components:
export-send.ts
```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

// Raw HTML exported from the gallery (not instrumented).
await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Your receipt",
html: exportedHtml,
});
```

## Quality checks
The editor runs checks as you edit so a template is inbox-ready before it goes out. Deckle surfaces:
CheckWhat it catches
Spam scoreContent and markup patterns that hurt deliverability, scored so you can fix them.
Broken linksLinks that don’t resolve, so recipients never hit a dead URL.
Missing variables{{variable}} placeholders with no value and no fallback, so nothing renders empty.
Give every variable a fallback
Use {{first_name | "there"}} so a missing value renders a friendly default instead of a blank. The editor flags placeholders without one.

## Next steps
Sending with templatesSend a template by id with variables, tracking, and per-send subject overrides.
Variables & personalizationFill placeholders from send data and contact fields, with fallbacks and conditionals.


========================================================================
URL: https://app.getdeckle.com/docs/domains/overview
Section: Domains & deliverability
========================================================================

Domains

# Add & verify a domain
Add your sending domain, publish the DNS records Deckle generates, and let verification poll until you're ready to send.
Every email you send through Deckle goes out from a domain you own. Adding one takes a few minutes: point a handful of DNS records at your provider, and Deckle watches for them to propagate.

## Why your own domain
Deckle follows Model A — you send from your own verified domain rather than a shared “from” address owned by the platform. That means the sending reputation you build is yours alone.
On a shared pool, one careless sender’s spam complaints can drag down deliverability for everyone on the same IPs. With your own domain, that can’t happen: a bad sender elsewhere never poisons your inbox placement, and the trust you earn with mailbox providers stays attached to your domain.

- Recipients see mail from your domain, not a generic relay address.
- Your engagement, bounce, and complaint history define your reputation.
- Authentication (DKIM, SPF, DMARC) is signed under your domain.

## Add a domain
Domains live in the account menu — open Domains from the top bar. Adding a domain creates the underlying AWS SES identity and hands you the DNS records to publish.

### Open Domains and add your domain
In the dashboard, open the account menu and go to Domains, then choose Add domain. Enter the domain you’ll send from, for example acme.com.

### Deckle creates the SES identity
Deckle registers the domain as an identity in AWS SES and generates the DNS records you need — DKIM keys, an SPF entry, and a DMARC record. They’re shown right on the domain’s page.

### Add the records at your DNS provider
Copy each record into your DNS host (Cloudflare, Route 53, Namecheap, or wherever your domain is managed). Keep the host, type, and value exactly as shown.

### Let verification auto-poll
Deckle continuously polls for the records and updates each one’s status — pending, verified, or failed. DNS changes can take anywhere from a few minutes to a few hours to propagate. Use the one-click Recheck button to poll again on demand.

### What the records look like
Each domain publishes three kinds of records. The exact tokens are unique to your domain — copy the real values from the domain’s page.
RecordTypeHostPurpose
DKIM (×3)CNAME<token>._domainkey.acme.comSigns your mail so mailbox providers can verify it wasn’t altered.
SPFTXT@Authorizes SES to send for you — v=spf1 include:amazonses.com ~all.
DMARCTXT_dmarc.acme.comSets your alignment policy — start with v=DMARC1; p=none.
DKIM is what gates sending; SPF and DMARC are verified by real DNS lookups and reported per record. See Authentication for the full breakdown of each record.
DKIM must verify before you can send
Deckle only unlocks sending from a domain once its DKIM records are attested by SES. Until the domain shows verified, sends from that address are blocked. SPF and DMARC are strongly recommended (and required by Gmail and Yahoo bulk-sender rules) but don’t gate a single transactional send on their own.

## Default sender
Each verified domain carries a default from name and address. Set these on the domain’s page — for example a name of Acme and an address of hello@acme.com.
The default sender fills in the from field when you compose a campaign or start an automation from that domain, so you don’t retype it every time. You can always override it per send — the from value on an API call just needs to belong to a verified domain, in the form "Name <addr@domain>" or a bare addr@domain.

## Next steps
AuthenticationPublish DKIM, SPF, and DMARC correctly and understand what each record proves.
DeliverabilityKeep complaint rates low, honor unsubscribes, and land in the inbox at scale.


========================================================================
URL: https://app.getdeckle.com/docs/domains/authentication
Section: Domains & deliverability
========================================================================

Domains

# DKIM, SPF & DMARC
The three DNS record sets that authenticate your mail so inboxes trust it — and how Deckle verifies each one.
When you add a domain, Deckle creates the SES identity and shows you the exact DNS records to publish at your provider. Three families of records do the work: DKIM proves the message wasn’t tampered with, SPF authorizes the sending host, and DMARC tells inboxes what to do when a check fails. Once they resolve, your mail authenticates cleanly and you can send from your own domain.

## Why three records
Mailbox providers won’t take your word that a message came from you — they check the DNS on your domain. Each record answers a different question, and Gmail’s and Yahoo’s bulk-sender rules expect all three to line up.
Because Deckle uses Model A, you send from a domain you own and verify, so authentication builds your reputation rather than a shared pool’s. That makes these records the foundation of your deliverability. Add them once in your DNS provider and Deckle keeps them under watch.
Where these come from
You don’t hand-craft any of this. In the dashboard, open Domains, add your domain, and Deckle generates the exact host and value for every record. This page explains what each one is for.

## DKIM
DKIM (DomainKeys Identified Mail) attaches a cryptographic signature to every message so the receiving inbox can confirm it really came from your domain and wasn’t altered in transit. Deckle provisions the keys through AWS SES, so you publish three CNAME records that point at SES-hosted values.
Each record lives at a host of the form <token>._domainkey.<domain>, where the tokens are generated for your identity:
bash
```
; DKIM — three CNAME records (values shown in the dashboard)
abc123._domainkey.acme.com. CNAME abc123.dkim.amazonses.com.
def456._domainkey.acme.com. CNAME def456.dkim.amazonses.com.
ghi789._domainkey.acme.com. CNAME ghi789.dkim.amazonses.com.
```
DKIM is SES-attested and gates sending: until AWS confirms all three CNAMEs resolve, the domain stays unverified and you can’t send from it. Verification auto-polls, and you can trigger a one-click recheck from the domain page.
Don't flatten the CNAMEs
Some DNS providers try to be helpful by resolving a CNAME to its target and storing an A record instead. DKIM breaks if that happens — the host must remain a real CNAME pointing at the *.dkim.amazonses.com value.

## SPF
SPF (Sender Policy Framework) lists which servers are allowed to send mail for your domain. Publish a single TXT record at the root host @ that authorizes Amazon SES:
bash
```
; SPF — TXT at the root of the domain
acme.com. TXT "v=spf1 include:amazonses.com ~all"
```
The ~all at the end is a soft-fail: unlisted senders are flagged rather than hard-rejected, which is the right default while you roll out. Keep one SPF record per domain — if you already have a v=spf1 record, merge include:amazonses.com into it rather than adding a second.

### Custom MAIL FROM
If you configure a custom MAIL FROM subdomain (recommended so the bounce/return-path domain aligns with yours), Deckle shows two more records at mail.<domain>: an MX record so SES can receive bounces, and its own SPF TXT.
bash
```
; Custom MAIL FROM — records at mail.<domain>
mail.acme.com. MX 10 feedback-smtp.us-east-1.amazonses.com.
mail.acme.com. TXT "v=spf1 include:amazonses.com ~all"
```

## DMARC
DMARC (Domain-based Message Authentication, Reporting & Conformance) ties DKIM and SPF together: it tells inboxes what to do with mail that fails those checks, and where to send aggregate reports. Publish a TXT record at _dmarc.<domain> whose value starts with v=DMARC1.
bash
```
; DMARC — TXT at _dmarc.<domain>
_dmarc.acme.com. TXT "v=DMARC1; p=none; rua=mailto:dmarc@acme.com"
```
Start with p=none. That’s a monitor-only policy — nothing gets blocked while you confirm your legitimate mail is authenticating. Once the aggregate reports look clean, you can tighten to p=quarantine and eventually p=reject.
A DMARC record is required for bulk senders
Gmail and Yahoo require at least a p=none DMARC policy to send bulk mail. Adding it early costs nothing and unlocks the stricter policies later.

## Record summary
Here’s every record at a glance. The exact hosts and values for your domain appear on its page in the dashboard.
RecordHostTypePurpose
DKIM (×3)<token>._domainkey.<domain>CNAMESigns mail; SES-attested and gates sending.
SPF@ (root)TXTAuthorizes SES: v=spf1 include:amazonses.com ~all.
MAIL FROM MXmail.<domain>MXReceives bounces for the custom return-path (optional).
MAIL FROM SPFmail.<domain>TXTAuthorizes SES for the MAIL FROM subdomain (optional).
DMARC_dmarc.<domain>TXTPolicy for failed checks; start with p=none.
How verification works
DKIM is confirmed by SES and gates whether the domain can send. SPF and DMARC are verified by real DNS lookups and shown per-record on the domain page, so you can see exactly which one is still propagating. DNS changes can take up to a few hours to appear.

## Next steps
One-click unsubscribeShip the List-Unsubscribe headers bulk-sender rules require alongside authentication.
Deliverability guideEverything beyond DNS: complaint rates, list hygiene, and staying in the inbox.


========================================================================
URL: https://app.getdeckle.com/docs/domains/unsubscribes
Section: Domains & deliverability
========================================================================

Domains & deliverability

# One-click unsubscribe
Every marketing email Deckle sends carries the headers and visible link that let recipients unsubscribe in a single click — and unsubscribing suppresses the contact automatically.
Bulk senders are now required to support one-click unsubscribe. Deckle handles this for you: marketing and broadcast sends ship with the right headers and a visible unsubscribe link, and the click flows through to a hosted preference page that suppresses the contact.

## Why it's required
Gmail and Yahoo's bulk-sender rules require that any sender delivering large volumes of mail supports one-click unsubscribe. A recipient must be able to opt out with a single action, without logging in or filling out a form, and you must honor that request promptly.
Alongside one-click unsubscribe, the same rules require authenticated mail (SPF, DKIM, and DMARC) and a low spam-complaint rate. Getting unsubscribe wrong hurts your deliverability directly — mailbox providers treat “this is spam” clicks as a much stronger negative signal than a clean unsubscribe. Making it easy to leave keeps your reputation healthy.
This applies to marketing mail
One-click unsubscribe is added to marketing and broadcast sends — campaigns, automations, and newsletters. Purely transactional messages (receipts, password resets) are not treated as bulk marketing and are out of scope for the requirement.

## What Deckle adds
When you send a campaign or a marketing automation, Deckle automatically attaches two headers and injects a visible unsubscribe link into the email. You don't configure anything — it rides on every eligible send from your verified domain.

### The headers
Deckle sets both the List-Unsubscribe header and the List-Unsubscribe-Post header. Together they tell Gmail and Yahoo that the message supports RFC 8058 one-click unsubscribe, which is what surfaces the native “Unsubscribe” control next to the sender name in the inbox.
http
```
List-Unsubscribe: <https://app.getdeckle.com/u/unsub_9f3c...>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
```
The List-Unsubscribe-Post: List-Unsubscribe=One-Click line is the piece that makes it a true one-click: the mailbox provider sends a single POST to the unsubscribe URL on the recipient's behalf, with no confirmation step, and Deckle records the opt-out.

### The visible link
Header-based unsubscribe only works in clients that support it. So Deckle also injects a visible unsubscribe link into the body of every marketing and broadcast email — typically in the footer, next to your sending address. This is a hard requirement of the bulk-sender rules, and it guarantees a working opt-out for every recipient regardless of their mail client.
Templates from the gallery
Templates in the gallery already include a footer with the unsubscribe link and your brand details. When you send them as part of a campaign or automation, the link is populated automatically — see the template gallery.

## The preference page
Both the header URL and the visible link point at a hosted preference page that Deckle runs for you. There's nothing to build or host yourself. When a recipient lands there, they can confirm their unsubscribe, and the page reflects the outcome back to them.

### Recipient clicks unsubscribe
Either the mailbox provider POSTs the one-click URL, or the recipient follows the visible link in the email footer to the hosted page.

### Deckle records the opt-out
The contact is marked unsubscribed and added to your suppression list. This happens immediately — there's no delay before the change takes effect.

### Future marketing sends skip them
Because the address is now suppressed, subsequent campaigns and marketing automations no longer target that contact.

## Unsubscribing suppresses the contact
An unsubscribe isn't just a flag on a contact — it adds the address to your suppression list with the reason unsubscribe. Suppression is enforced platform-wide: any attempt to send to a suppressed address is rejected with a 422, so an unsubscribed contact can't be re-emailed by accident.
The unsubscribe reason sits alongside the other ways an address lands on the suppression list.
ReasonHow it's added
unsubscribeRecipient used one-click unsubscribe or the hosted preference page.
hard_bounceSES reported a permanent bounce; added automatically.
complaintRecipient marked the message as spam; added automatically.
manualYou added the address by hand in the dashboard or via the API.
If someone unsubscribes by mistake and asks to be re-added, you can remove them from the suppression list — in the dashboard, or with deckle.suppressions.delete(email). Only do this with the contact's explicit consent; re-emailing an address that opted out is the fastest way to earn spam complaints.
Keep complaints low
A frictionless unsubscribe is your best defense against complaints. Aim to keep your complaint rate under 0.3% — the dashboard warns you as you approach the threshold. The deliverability guide covers the full checklist.

## Next steps
Deliverability guideThe full bulk-sender checklist — authentication, unsubscribe, complaint rate, and list hygiene.
SuppressionsInspect and manage the addresses Deckle will never send to, including unsubscribes.


========================================================================
URL: https://app.getdeckle.com/docs/domains/deliverability
Section: Domains & deliverability
========================================================================

Domains & deliverability

# Deliverability guide
What it takes to land in the inbox as a bulk sender — authentication, complaint rate, and list hygiene, all riding on your own domain's reputation.
Because Deckle sends from a domain you own and verify (Model A), your deliverability is yours to protect — one noisy sender can never poison a shared pool. The flip side is that the fundamentals are on you. Here’s the short list that keeps you in the inbox.

## Bulk sender essentials
Gmail and Yahoo enforce a baseline for anyone sending at volume. Deckle handles some of this for you and gives you the tools for the rest. Cover all of it:

- SPF, DKIM, and DMARC — authenticate every message. Publish all three when you verify your domain. See Domain authentication.
- One-click unsubscribe — every marketing send includes List-Unsubscribe headers and a visible link, as the bulk-sender rules require.
- Complaint rate under 0.3% — keep spam complaints well below the threshold mailbox providers enforce.
- Enforced suppression — Deckle never sends to a suppressed address, and hard bounces and complaints are added automatically.
- Clean template markup — use the gallery templates or keep your HTML simple and inline-styled; messy markup trips spam filters.
- A plain-text alternative on every HTML email — Deckle’s template renderer produces one automatically alongside the HTML.
- Valid TLS and PTR — encrypted transport and reverse DNS are handled for you by AWS SES.

## Watch your complaint rate
Your complaint rate is the share of delivered messages that recipients mark as spam. It is the single metric most likely to get your sending throttled, so treat the 0.3% ceiling as a hard line, not a target.
Keep complaints under 0.3%
Mailbox providers start penalizing senders that cross a 0.3% complaint rate. The dashboard warns you as you approach the threshold — if you see that warning, pause and review who you're emailing before you send more.

## List hygiene
Most deliverability problems trace back to who you send to, not what you send. A smaller, engaged list beats a large, stale one every time. Make these habits:

- Send to engaged contacts. Favor people who have opened or clicked recently. Build a live segment for engagement and target it rather than blasting your whole list.
- Honor unsubscribes. Unsubscribing suppresses the contact automatically — never re-import or re-add someone who opted out.
- Remove hard bounces. Hard bounces are auto-suppressed, so repeatedly sending to dead addresses can’t happen — but clean them out of your source lists too so your metrics stay honest.The suppression list is your safety net for all of this. It records the reason for every entry — hard_bounce, complaint, unsubscribe, or manual — and Deckle rejects any send to a suppressed address with a 422.

## Next steps
Domain authenticationPublish the DKIM, SPF, and DMARC records that authenticate every message you send.
SuppressionsSee how bounces, complaints, and unsubscribes are enforced across every send.


========================================================================
URL: https://app.getdeckle.com/docs/webhooks/introduction
Section: Webhooks
========================================================================

Webhooks

# Webhooks
Get notified in real time when your emails are delivered, bounced, opened, clicked, or complained about — Deckle POSTs each event to an endpoint you control.
Instead of polling the API for the status of every send, register an HTTPS endpoint and let Deckle push events to you as they happen. Each delivery is a signed POST you can verify and act on — sync a database, alert a channel, or trigger downstream work.

## What are webhooks
A webhook is an HTTPS URL you own that Deckle sends events to. Whenever something happens to an email you sent — it’s delivered, it bounces, a recipient opens or clicks it, or someone marks it as spam — Deckle makes an HTTP POST request to your endpoint with a JSON body describing the event.
Your endpoint responds with a 2xx status to acknowledge receipt. Because the request originates from Deckle and not from a browser session, every delivery is signed so you can confirm it’s genuine before you trust it. See Verify signatures for how to check the signature.
HTTPS only
Endpoints must use https://. Deckle will not deliver events to plaintext HTTP URLs.

## Register an endpoint
Add and manage endpoints from the dashboard. Each project has its own webhook endpoints, and each endpoint subscribes to the specific event types you care about.

### Open Developers → Webhooks
In the dashboard on app.getdeckle.com, go to Developers and open the Webhooks section.

### Add your HTTPS URL and choose events
Click Add endpoint, paste your public HTTPS URL (for example https://api.acme.com/webhooks/deckle), and select which event types this endpoint should receive.

### Copy the signing secret
Deckle shows the endpoint’s signing secret (whsec_...) once, at creation. Copy it and store it securely — you’ll need it to verify incoming requests, and it’s never shown again.The signing secret is shown once
Store your whsec_... secret in a secure place right away. If you lose it, rotate the secret from the dashboard to generate a new one.

## The payload
Every delivery is a POST with a JSON body containing the event type, an ISO 8601 created_at timestamp, and a data object with the details for that event.
json
```
{
"type": "email.delivered",
"created_at": "2026-07-10T18:24:05.123Z",
"data": {
"id": "email_9fQ2xk7Lp",
"to": "jane@example.com",
"subject": "Welcome to Acme 👋"
}
}
```
Each request also carries two headers you’ll want to read:
HeaderDescription
X-Deckle-SignatureHMAC-SHA256 of the raw request body, hex-encoded, computed with your endpoint’s whsec_... secret. Use it to verify authenticity.
X-Deckle-EventThe event type, mirroring type in the body — handy for routing before you parse the payload.
Verify against the raw body
Compute the signature over the exact bytes Deckle sent — the raw request body, before any JSON parsing or re-serialization. See Verify signatures for a copy-paste example using verifyWebhookSignature from @deckle/sdk.

## Event types
Endpoints can subscribe to any combination of the following event types. The canonical data schema for each one is documented on Event types.

- email.delivered — the message was accepted by the recipient’s mail server.
- email.bounced — the message could not be delivered; hard bounces are auto-suppressed.
- email.complained — the recipient marked the message as spam; the address is auto-suppressed.
- email.opened — the recipient opened the message (tracked sends only).
- email.clicked — the recipient clicked a link; data includes the url.

## Delivery
Deckle delivers each event on a best-effort basis to every active endpoint subscribed to that event type. An endpoint that’s disabled, or not subscribed to the event, is skipped. To keep receiving events, respond with a 2xx status quickly and do any heavy processing asynchronously.
You don’t need real traffic to check your integration. From the dashboard, send a test.ping event to any endpoint to confirm it’s reachable and that your signature verification works end to end.
Test before you go live
Use the test.ping button on the endpoint in the dashboard to fire a sample delivery, then confirm your handler returns 2xx and the signature validates.

## Next steps
Verify signaturesValidate the X-Deckle-Signature header against the raw body with the SDK helper.
Event typesThe full list of outbound events and the data payload each one carries.


========================================================================
URL: https://app.getdeckle.com/docs/webhooks/verify
Section: Webhooks
========================================================================

Webhooks

# Verifying signatures
Confirm that every webhook request really came from Deckle by validating its signature before you trust the payload.
Your webhook endpoint is a public URL, so anyone can POST to it. Deckle signs each delivery so you can prove the request came from us and the body wasn't tampered with. Verify the signature on every request and reject anything that doesn't match.

## Why verify
Because your endpoint is reachable by anyone, a signature is the only thing that distinguishes a genuine Deckle delivery from a forged one. Verifying it lets you trust that the event is real before you act on it — updating a record, suppressing a contact, or firing a downstream job. Skip verification and an attacker can replay or fake events against your system.
Each webhook endpoint you register in the dashboard has its own signing secret. Deckle shows it once, prefixed with whsec_. Store it as an environment variable and never commit it. See the webhooks overview for how to register an endpoint and retrieve the secret.

## The signature
Every delivery includes an X-Deckle-Signature header. Its value is the HMAC-SHA256 of the raw request body, keyed with your endpoint's whsec_ secret, encoded as lowercase hex. Deckle also sends an X-Deckle-Event header naming the event type.
To verify, you recompute the HMAC over the exact bytes you received and compare it to the header. If they match, the request is authentic and unmodified.
Verify against the raw body
Always compute the HMAC over the raw request body, exactly as received, before calling JSON.parse. Parsing and re-serializing can reorder keys or change whitespace, which produces a different signature and makes every verification fail.

## Verify with the SDK
The Node SDK ships a verifyWebhookSignature helper. Read the raw body as text, pass it with the signature header and your secret, and it returns whether the request is valid. In a Next.js Route Handler, calling req.text() gives you the raw body directly — do that before you parse.
app/api/webhooks/deckle/route.ts
```
import { verifyWebhookSignature } from "@deckle/sdk";

export async function POST(req: Request) {
// Read the RAW body first — do not parse before verifying.
const body = await req.text();
const signature = req.headers.get("x-deckle-signature");
const secret = process.env.DECKLE_WEBHOOK_SECRET!;

if (!verifyWebhookSignature(body, signature, secret)) {
return new Response("Invalid signature", { status: 401 });
}

// Signature is valid — now it's safe to parse.
const event = JSON.parse(body);

switch (event.type) {
case "email.delivered":
// handle delivery
break;
case "email.bounced":
// handle bounce
break;
}

return new Response("ok", { status: 200 });
}
```
Return a 2xx as soon as you've verified and accepted the event. Deckle treats any non-2xx response as a failed delivery.

## Verify manually
You don't need the SDK — the check is a few lines with Node's built-in crypto module. Recompute the HMAC-SHA256 hex digest of the raw body with your secret, then compare it to the header using a timing-safe comparison so you don't leak information through response timing.
verify.ts
```
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, signature: string | null, secret: string) {
if (!signature) return false;

const expected = createHmac("sha256", secret)
.update(rawBody, "utf8")
.digest("hex");

const a = Buffer.from(expected, "hex");
const b = Buffer.from(signature, "hex");

// Bail early if lengths differ — timingSafeEqual throws otherwise.
if (a.length !== b.length) return false;

return timingSafeEqual(a, b);
}
```

### Getting the raw body
The signature only matches if you hash the untouched bytes. In frameworks that eagerly parse JSON (like Express with express.json()), disable body parsing for the webhook route or capture the raw buffer first — otherwise the parsed-and-reserialized body won't match the signature.

## Next steps
Webhook eventsThe event types Deckle sends and the payload shape for each.
Node SDKInstall @deckle/sdk and use verifyWebhookSignature and every resource.


========================================================================
URL: https://app.getdeckle.com/docs/webhooks/events
Section: Webhooks
========================================================================

Webhooks

# Webhook event types
The events Deckle sends to your endpoints, and what each one means.
Every webhook delivery has a type that tells you what happened, and a data object with the details. Subscribe an endpoint to the events you care about and Deckle POSTs each one to you as it fires.

## Events
Deckle emits five email lifecycle events. Delivery, bounce, and complaint events come straight from AWS SES; opens and clicks are tracked on template sends. Each event is delivered to every active endpoint subscribed to it.
EventFired when
email.deliveredSES confirmed the message was delivered to the recipient's mail server.
email.bouncedThe message hard-bounced. The address is also added to your suppression list.
email.complainedThe recipient marked the message as spam. The address is also added to your suppression list.
email.openedThe tracking pixel was loaded — the recipient opened the email.
email.clickedThe recipient clicked a tracked link in the email.
Also: test.ping
The Send test event button in the dashboard delivers a test.ping event so you can confirm your endpoint is reachable before real events start flowing.

## The data object
Each event's data object carries the email log id, the recipient, and the subject — enough to tie the event back to the message you sent. email.clicked events also include the url that was clicked, so you can attribute engagement to a specific link.
Full payload schemas
The exact fields on each event's data object live in the webhook events API reference.

## Next steps
Webhook events referenceThe canonical payload schema for every event type and its data object.
Verify signaturesCheck the X-Deckle-Signature header so you only trust events from Deckle.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/overview
Section: Integrations
========================================================================

Integrations

# Overview
Connect Deckle to the tools you already use — send from your auth stack, sync contacts, and automate everything.
Every Deckle integration is one of three shapes. Knowing which shape a connector is tells you exactly how it plugs in — and all three are built on the same public API, webhooks, and SMTP relay, so anything not listed can still be wired up with a few lines of code.

## The three shapes
Send-throughRoute a tool's auth & transactional email through Deckle over SMTP — e.g. Supabase, Clerk, Auth0, WordPress.
Inbound dataStream external contacts and events into Deckle to drive automations — e.g. Segment, Shopify, Stripe.
BridgeTrigger on Deckle events and act on the Deckle API from no-code tools — e.g. Zapier, Make.

## How they work
Send-through connectors reuse Deckle’s SMTP relay: you generate a secret key and paste it as the SMTP password, so the tool’s email flows through your verified domain. Inbound connectors give you a signed endpoint URL; the provider posts to it, and Deckle normalizes each payload into a contact or event — which then enrolls matching contacts into your live automations. Bridge connectors use Deckle’s outbound webhooks as triggers and the REST API as actions.
Don't see your tool?
If a connector isn’t listed yet, you can almost always achieve the same result with Zapier, an SMTP config, or a direct API call. Browse the full catalog under Integrations in the dashboard.

## Manage integrations
Connect, disconnect, and rotate credentials from the Integrations page in your dashboard. Each connector has its own setup panel — SMTP settings for send-through, an endpoint + signing secret for inbound, and trigger/action references for bridges.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/activepieces
Section: Integrations
========================================================================

Integrations · Bridge

# Activepieces
Build no-code automations between Deckle and other apps.
Use Deckle in Activepieces flows — an open-source Zapier alternative — via HTTP steps against the Deckle API and webhooks.

## Set it up

- Open Integrations → Activepieces and click Connect to generate a secret key.
- In Activepieces, add the Deckle app and authenticate with the key.
- Use Deckle triggers and actions to build your workflow.

## Triggers & actions
Triggers: contact.created, event.recorded
Actions: Create or update contact, Record event, Send email

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open ActivepiecesConnect Activepieces from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/airtable
Section: Integrations
========================================================================

Integrations · Bridge

# Airtable
Sync Airtable records into Deckle audiences.
Use Airtable automations (or Zapier) to push records into Deckle as contacts.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- Connect Airtable to Deckle with Zapier or Make.
- Map records to contacts, or events to automation triggers, and send a test.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open AirtableConnect Airtable from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/amazon-s3
Section: Integrations
========================================================================

Integrations · Bridge

# Amazon S3
Import and export contact data via S3 buckets.
Batch-import contacts from S3 and export engagement data back to your bucket. On the roadmap.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- Connect Amazon S3 to Deckle with Zapier or Make.
- Map records to contacts, or events to automation triggers, and send a test.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open Amazon S3Connect Amazon S3 from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/amplitude
Section: Integrations
========================================================================

Integrations · Bridge

# Amplitude
Send Amplitude cohorts and events into Deckle.
Forward Amplitude events to Deckle's /v1/events endpoint (via Zapier or a handler) to power behavioral campaigns.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- In Amplitude, add a webhook or destination for the events you care about.
- Point it at Deckle's POST /v1/events (directly or via Zapier) so events trigger automations.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open AmplitudeConnect Amplitude from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/attio
Section: Integrations
========================================================================

Integrations · Bridge

# Attio
Sync Attio people and companies into Deckle.
Push Attio records into Deckle via Zapier or Attio's automations calling /v1/contacts, so your CRM audience is ready for marketing email.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- In Attio, add a webhook (or Zapier trigger) for new customers and records.
- Sync them to Deckle's /v1/contacts and record activity via /v1/events.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open AttioConnect Attio from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/authjs
Section: Integrations
========================================================================

Integrations · Send-through

# Auth.js / NextAuth
Send magic-link and verification emails from Auth.js through Deckle.
Wire the Auth.js email provider (or the Deckle SDK) to send passwordless magic links and verification emails via Deckle.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- Set the Email provider's `server` to the SMTP settings below in your Auth.js config.
- Use the key as the SMTP password and set `from` to your verified domain.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open Auth.js / NextAuthConnect Auth.js / NextAuth from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/auth0
Section: Integrations
========================================================================

Integrations · Send-through

# Auth0
Use Deckle as the SMTP provider for Auth0 tenant emails.
Configure Auth0's custom email provider to send through Deckle's SMTP relay for verification, password-reset, and MFA emails.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- In Auth0 → Branding → Email Provider, select SMTP.
- Enter the host, port, username, and the key as the password.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open Auth0Connect Auth0 from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/better-auth
Section: Integrations
========================================================================

Integrations · Send-through

# Better Auth
Plug Deckle into Better Auth's sendEmail hook for auth emails.
Use Deckle in Better Auth's email hooks to deliver verification, reset, and OTP emails through your verified domain.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- In your Better Auth config, send from the `sendVerificationEmail` / `sendResetPassword` hooks over SMTP.
- Use the key as the SMTP password.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open Better AuthConnect Better Auth from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/bigquery
Section: Integrations
========================================================================

Integrations · Bridge

# BigQuery
Sync BigQuery segments into Deckle audiences.
Reverse-ETL audience tables from BigQuery into Deckle contacts. On the roadmap.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- Connect BigQuery to Deckle with Zapier or Make.
- Map records to contacts, or events to automation triggers, and send a test.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open BigQueryConnect BigQuery from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/bubble
Section: Integrations
========================================================================

Integrations · Send-through

# Bubble
Send email from Bubble apps via the Deckle API connector.
Call the Deckle API from Bubble's API Connector to send transactional email and sync contacts from your no-code app.

## Set it up

- Generate a Deckle secret key below and copy it.
- In Bubble → Plugins → API Connector, add a new API with a Bearer Authorization header using the key.
- Call POST https://app.getdeckle.com/v1/send to send, or /v1/contacts to sync contacts.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open BubbleConnect Bubble from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/clay
Section: Integrations
========================================================================

Integrations · Bridge

# Clay
Push enriched leads from Clay into Deckle.
Use Clay's HTTP API column to POST enriched leads to Deckle's /v1/contacts endpoint, ready for outreach.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- In Clay, add an HTTP/API step on your enriched rows.
- POST each row to Deckle's /v1/contacts with the email and custom fields.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open ClayConnect Clay from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/clerk
Section: Integrations
========================================================================

Integrations · Send-through

# Clerk
Deliver Clerk authentication emails — sign-in links, verification codes, invitations — from your own verified domain through Deckle.
Clerk supports a custom SMTP provider for its authentication emails. Point it at Deckle so every auth email routes through your verified domain on AWS SES with full delivery and open tracking.

## Set it up

### Connect Clerk in Deckle
Open Integrations → Clerk and click Connect. Copy the secret key Deckle shows once.

### Add a custom SMTP provider in Clerk
In the Clerk dashboard, go to Customization → Email and choose a custom SMTP provider.

### Paste the connection settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key

### Verify your sender domain
Add and verify your from-domain under Domains so Clerk mail passes SPF and DKIM.
Also works for other auth stacks
The same SMTP flow powers Supabase, Auth0, Auth.js, and Better Auth — connect, paste the settings, verify your domain.

## Next steps
API keysHow the secret key that doubles as your SMTP password works.
Domains overviewVerify the domain your Clerk auth emails send from.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/convex
Section: Integrations
========================================================================

Integrations · Send-through

# Convex
Send email from Convex functions via the Deckle API.
Call the Deckle API from your Convex actions to send transactional email — receipts, magic links, and notifications.

## Set it up

- Generate a Deckle secret key below and copy it.
- Store it as a Convex environment variable.
- Call POST https://app.getdeckle.com/v1/send from a Convex action.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open ConvexConnect Convex from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/courier
Section: Integrations
========================================================================

Integrations · Send-through

# Courier
Deliver Courier's email channel through Deckle.
Use Deckle as the email provider in Courier so your product notifications send through your verified domain with full delivery logs.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- In Courier → Channels, add an SMTP email provider.
- Enter the host, port, username, and the key as the password.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open CourierConnect Courier from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/dittofeed
Section: Integrations
========================================================================

Integrations · Send-through

# Dittofeed
Route Dittofeed's email through Deckle.
Use Deckle as the SMTP email provider in Dittofeed so your customer-messaging journeys deliver through your domain.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- In Dittofeed, configure an SMTP email provider.
- Enter the host, port, username, and the key as the password.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open DittofeedConnect Dittofeed from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/email-love
Section: Integrations
========================================================================

Integrations · Import

# Email Love
Start from Email Love's gallery of proven designs.
Bring inspiration and HTML from Email Love's curated gallery into your Deckle templates.

## Import into Deckle
Email Love is an import source — there’s no live connection. Export your HTML from Email Love and create a template from it under Templates.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open Email LoveConnect Email Love from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/emailify
Section: Integrations
========================================================================

Integrations · Import

# Emailify
Import MJML/HTML templates designed in Emailify (Figma).
Export email designs from the Emailify Figma plugin and import the HTML into Deckle templates.

## Import into Deckle
Emailify is an import source — there’s no live connection. Export your HTML from Emailify and create a template from it under Templates.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open EmailifyConnect Emailify from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/fivetran
Section: Integrations
========================================================================

Integrations · Bridge

# Fivetran
Load warehouse data into Deckle audiences via Fivetran.
Sync modeled customer data from your warehouse into Deckle on a schedule using Fivetran. On the roadmap.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- Connect Fivetran to Deckle with Zapier or Make.
- Map records to contacts, or events to automation triggers, and send a test.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open FivetranConnect Fivetran from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/framer
Section: Integrations
========================================================================

Integrations · Bridge

# Framer
Capture Framer form submissions as Deckle contacts.
Forward Framer form submissions to Deckle via Zapier or a webhook so new leads land in your audience and trigger welcome automations.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- In Framer, connect your form or record to Zapier (or a webhook).
- Send new leads to Deckle's /v1/contacts so they enter your audience and automations.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open FramerConnect Framer from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/google-ads
Section: Integrations
========================================================================

Integrations · Bridge

# Google Ads
Sync Deckle audiences to Google Ads Customer Match.
Export engaged segments to Google Ads for retargeting and lookalike campaigns. On the roadmap.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- Connect Google Ads to Deckle with Zapier or Make.
- Map records to contacts, or events to automation triggers, and send a test.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open Google AdsConnect Google Ads from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/google-sheets
Section: Integrations
========================================================================

Integrations · Bridge

# Google Sheets
Add or update Deckle contacts from a spreadsheet.
Sync rows from Google Sheets into Deckle contacts via Zapier or Make.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- Connect Google Sheets to Deckle with Zapier or Make.
- Map records to contacts, or events to automation triggers, and send a test.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open Google SheetsConnect Google Sheets from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/hubspot
Section: Integrations
========================================================================

Integrations · Bridge

# HubSpot
Two-way contact sync between HubSpot and Deckle.
Keep contacts and properties in sync between HubSpot and Deckle so marketing email and CRM stay aligned. Native two-way sync is on the roadmap; today, bridge via Zapier.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- In HubSpot, add a webhook (or Zapier trigger) for new customers and records.
- Sync them to Deckle's /v1/contacts and record activity via /v1/events.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open HubSpotConnect HubSpot from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/inngest
Section: Integrations
========================================================================

Integrations · Send-through

# Inngest
Send email from Inngest functions with Deckle.
Call the Deckle API from Inngest functions to send email as part of your event-driven and scheduled workflows.

## Set it up

- Generate a Deckle secret key below and copy it.
- Add it to your Inngest app's environment.
- Call the Deckle API (or SDK) from a step in your Inngest function.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open InngestConnect Inngest from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/integrately
Section: Integrations
========================================================================

Integrations · Bridge

# Integrately
One-click automations connecting Deckle to popular apps.
Connect Deckle to other tools with Integrately's ready-made automations, calling the Deckle API for contacts, events, and sending.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- In Integrately, add the Deckle app (or an HTTP node) and authenticate with the key.
- Build a flow: your trigger → Deckle "create or update contact", "record event", or "send email".

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open IntegratelyConnect Integrately from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/intercom
Section: Integrations
========================================================================

Integrations · Inbound

# Intercom
Sync Intercom contacts and events into Deckle.
Add Deckle as an Intercom webhook. New contacts and users become Deckle contacts, and other topics become events for lifecycle and re-engagement email.

## Set it up

- Click Connect to generate your endpoint URL and signing secret.
- In Intercom, add a webhook pointed at the endpoint URL and set the signing secret.
- Trigger a test event — the contact or event appears in Deckle within seconds.

## How data maps

- contact.* / user.* → contact
- other topics → event (topic name)Requests are verified via the x-hub-signature header using your signing secret.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open IntercomConnect Intercom from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/kinde
Section: Integrations
========================================================================

Integrations · Send-through

# Kinde
Send Kinde authentication emails through Deckle.
Point Kinde's email at Deckle's SMTP relay so verification, invitation, and password-reset emails send from your verified domain.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- In Kinde → Settings → Email, configure a custom SMTP provider.
- Enter the host, port, username, and the key as the password.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open KindeConnect Kinde from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/knock
Section: Integrations
========================================================================

Integrations · Send-through

# Knock
Send Knock's email notifications through Deckle.
Add Deckle as an SMTP email channel in Knock so your notification workflows deliver through your verified domain.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- In Knock → Channels, add an SMTP email channel.
- Enter the host, port, username, and the key as the password.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open KnockConnect Knock from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/make
Section: Integrations
========================================================================

Integrations · Bridge

# Make
Build visual automations between Deckle and thousands of apps.
Use Deckle in Make (Integromat) scenarios: watch for contacts/events via webhooks, and call the Deckle API to sync contacts, record events, and send email.

## Set it up

- Open Integrations → Make and click Connect to generate a secret key.
- In Make, add the Deckle app and authenticate with the key.
- Use Deckle triggers and actions to build your workflow.

## Triggers & actions
Triggers: contact.created, contact.updated, event.recorded
Actions: Create or update contact, Record event, Send email

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open MakeConnect Make from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/medusa
Section: Integrations
========================================================================

Integrations · Send-through

# Medusa
Send Medusa order & customer emails through Deckle.
Use a Medusa notification provider to send order-confirmation, shipping, and account emails through Deckle over SMTP or the API.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- Add an SMTP notification provider in your Medusa config.
- Enter the host, port, username, and the key as the password.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open MedusaConnect Medusa from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/meta-lead-ads
Section: Integrations
========================================================================

Integrations · Bridge

# Meta Lead Ads
Capture Facebook & Instagram lead-form submissions as contacts.
Ingest Meta Lead Ads submissions so new leads land in Deckle and trigger instant follow-up email. On the roadmap; today, bridge via Zapier.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- Connect Meta Lead Ads to Deckle with Zapier or Make.
- Map records to contacts, or events to automation triggers, and send a test.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open Meta Lead AdsConnect Meta Lead Ads from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/mixpanel
Section: Integrations
========================================================================

Integrations · Bridge

# Mixpanel
Turn Mixpanel events into Deckle automation triggers.
Forward Mixpanel events to Deckle's /v1/events endpoint via Zapier so product analytics can trigger onboarding and re-engagement email.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- In Mixpanel, add a webhook or destination for the events you care about.
- Point it at Deckle's POST /v1/events (directly or via Zapier) so events trigger automations.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open MixpanelConnect Mixpanel from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/n8n
Section: Integrations
========================================================================

Integrations · Bridge

# n8n
Self-hostable workflows using the Deckle API via HTTP nodes.
Orchestrate Deckle from n8n workflows using HTTP Request nodes against the Deckle API, and Deckle webhooks as triggers.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- In n8n, add the Deckle app (or an HTTP node) and authenticate with the key.
- Build a flow: your trigger → Deckle "create or update contact", "record event", or "send email".

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open n8nConnect n8n from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/notion
Section: Integrations
========================================================================

Integrations · Bridge

# Notion
Sync a Notion database of people into Deckle.
Keep a Notion contacts database in sync with your Deckle audience via Zapier or Make.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- Connect Notion to Deckle with Zapier or Make.
- Map records to contacts, or events to automation triggers, and send a test.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open NotionConnect Notion from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/novu
Section: Integrations
========================================================================

Integrations · Send-through

# Novu
Use Deckle as Novu's email delivery provider.
Configure Deckle as a custom SMTP email provider in Novu so your notification workflows deliver email through your domain.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- In Novu → Integrations Store, add a custom SMTP email provider.
- Enter the host, port, username, and the key as the password.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open NovuConnect Novu from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/payload
Section: Integrations
========================================================================

Integrations · Send-through

# Payload
Send Payload CMS transactional email through Deckle.
Configure Payload's email adapter to send through Deckle over SMTP — verification, password resets, and admin notifications.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- In your Payload config, set the nodemailer SMTP transport to the settings below.
- Use the key as the SMTP password and set `defaultFromAddress` to your verified domain.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open PayloadConnect Payload from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/pipedream
Section: Integrations
========================================================================

Integrations · Bridge

# Pipedream
Automate Deckle from Pipedream workflows.
Use Deckle in Pipedream workflows: trigger on Deckle webhooks and call the Deckle API to sync contacts, record events, and send email.

## Set it up

- Open Integrations → Pipedream and click Connect to generate a secret key.
- In Pipedream, add the Deckle app and authenticate with the key.
- Use Deckle triggers and actions to build your workflow.

## Triggers & actions
Triggers: contact.created, event.recorded
Actions: Create or update contact, Record event, Send email

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open PipedreamConnect Pipedream from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/polar
Section: Integrations
========================================================================

Integrations · Inbound

# Polar
Sync Polar customers, orders, and subscriptions into Deckle.
Add Deckle as a Polar webhook endpoint. Orders and subscriptions become contacts and events that trigger post-purchase, dunning, and win-back automations.

## Set it up

- Click Connect to generate your endpoint URL and signing secret.
- In Polar, add a webhook pointed at the endpoint URL and set the signing secret.
- Trigger a test event — the contact or event appears in Deckle within seconds.

## How data maps

- order.created → contact + event order.completed
- subscription.active → contact
- subscription.canceled → event subscription.canceledRequests are verified via the webhook-signature header using your signing secret.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open PolarConnect Polar from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/posthog
Section: Integrations
========================================================================

Integrations · Inbound

# PostHog
Trigger Deckle automations from PostHog product events.
Point a PostHog HTTP webhook destination at Deckle. Events become Deckle events (and $identify calls become contacts) so product behavior drives lifecycle email.

## Set it up

- Click Connect to generate your endpoint URL and signing secret.
- In PostHog, add a webhook pointed at the endpoint URL and set the signing secret.
- Trigger a test event — the contact or event appears in Deckle within seconds.

## How data maps

- $identify / $set → contact (traits → custom fields)
- any event → event (name + properties)Requests are verified via the x-deckle-secret header using your signing secret.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open PostHogConnect PostHog from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/rudderstack
Section: Integrations
========================================================================

Integrations · Inbound

# RudderStack
Route RudderStack events into Deckle as contacts and events.
Add a RudderStack Webhook destination pointed at Deckle. identify calls upsert contacts and track calls become events — the same mapping as Segment.

## Set it up

- Click Connect to generate your endpoint URL and signing secret.
- In RudderStack, add a webhook pointed at the endpoint URL and set the signing secret.
- Trigger a test event — the contact or event appears in Deckle within seconds.

## How data maps

- identify → contact
- track → event
- page / screen → eventRequests are verified via the x-signature header using your signing secret.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open RudderStackConnect RudderStack from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/salesforce
Section: Integrations
========================================================================

Integrations · Bridge

# Salesforce
Sync Salesforce leads and contacts into your Deckle audience.
Connect Salesforce to push leads and contacts into Deckle and reflect email engagement back on the record. Native sync is on the roadmap; today, bridge via Zapier.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- In Salesforce, add a webhook (or Zapier trigger) for new customers and records.
- Sync them to Deckle's /v1/contacts and record activity via /v1/events.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open SalesforceConnect Salesforce from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/segment
Section: Integrations
========================================================================

Integrations · Inbound

# Segment
Stream Segment identify and track calls into Deckle contacts and events — automatically enrolling contacts into matching automations.
Add Deckle as a Segment Webhook (Actions) destination. Every identify upserts a contact and every track becomes an event, so product and marketing data flows straight into your audience and lifecycle automations.

## Set it up

### Connect Segment in Deckle
Open Integrations → Segment and click Connect. Deckle generates your endpoint URL and a signing secret — copy both. The secret is shown once.

### Add a Webhook destination in Segment
In Segment, add the Webhooks destination to your source. Set the webhook URL to the endpoint from the previous step, and set the shared secret to your Deckle signing secret.

### Send a test event
Trigger an identify or track from your source. It appears as a contact or event in Deckle within seconds.

## How data maps
Segment callBecomes
identifyA contact (traits.email → email, name → name, remaining traits → custom fields)
trackAn event named after the Segment event, with properties as event data
page / screenAn event (page / screen)
groupContact company data (when an email resolves)
Events drive automations
A track event uses its name verbatim as the automation trigger. Create an automation triggered by that exact event name and matching contacts enroll automatically.

## Request signing
Every request is signed so Deckle can trust it’s from your Segment source. Segment sends an x-signature header — the HMAC-SHA1 of the raw request body, keyed with your shared secret. Deckle recomputes and compares it in constant time; a mismatch is rejected with 401. This is the same scheme you can verify yourself:
verify.ts
```
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: string, signature: string, secret: string) {
const expected = createHmac("sha1", secret).update(rawBody, "utf8").digest("hex");
const a = Buffer.from(signature);
const b = Buffer.from(expected);
return a.length === b.length && timingSafeEqual(a, b);
}
```

## Next steps
ContactsHow contacts are stored, deduplicated by email, and enriched with custom fields.
AutomationsTrigger lifecycle email from the events your Segment source streams in.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/shopify
Section: Integrations
========================================================================

Integrations · Inbound

# Shopify
Sync Shopify customers and orders into Deckle to power abandoned-cart, order-confirmation, and win-back automations.
Add Deckle as a Shopify webhook endpoint. New customers become contacts, and orders and checkouts become events that enroll contacts into your lifecycle automations.

## Set it up

### Connect Shopify in Deckle
Open Integrations → Shopify, click Connect, and copy the endpoint URL and signing secret (shown once).

### Create webhooks in Shopify
In Shopify admin → Settings → Notifications → Webhooks (or via the Admin API), add webhooks pointed at your endpoint URL for the topics below. Set the webhook signing secret to your Deckle signing secret.

### Place a test order
The customer and order appear in Deckle within seconds, and any matching automation enrolls.

## How data maps
Shopify topicBecomes
customers/createA contact (email + name)
orders/createA contact + an order.completed event (total, currency, order number)
checkouts/createA cart.abandoned event (recovery URL)
Signature verification
Shopify signs each webhook with the base64 HMAC-SHA256 of the raw body in the x-shopify-hmac-sha256 header. Deckle recomputes and compares it with your signing secret; mismatches are rejected. The event topic is read from x-shopify-topic.

## Next steps
AutomationsBuild abandoned-cart and post-purchase flows off order.completed and cart.abandoned.
ContactsHow Shopify customers are stored and deduplicated by email.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/slack
Section: Integrations
========================================================================

Integrations · Bridge

# Slack
Get Slack alerts for sends, bounces, and new contacts.
Point a Deckle webhook at a Slack Incoming Webhook (directly or via Zapier) to post bounces, new signups, and campaign sends to a channel.

## Set it up

- In Developers → Webhooks, add a webhook subscribed to the events you want.
- Create an incoming webhook in Slack.
- Connect the two with Zapier (or a small relay) so Deckle events post to Slack.

## Triggers & actions
Triggers: email.bounced, contact.created, email.delivered

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open SlackConnect Slack from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/snowflake
Section: Integrations
========================================================================

Integrations · Bridge

# Snowflake
Sync audiences from Snowflake into Deckle (reverse ETL).
Push modeled audience segments from Snowflake into Deckle on a schedule. On the roadmap.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- Connect Snowflake to Deckle with Zapier or Make.
- Map records to contacts, or events to automation triggers, and send a test.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open SnowflakeConnect Snowflake from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/strapi
Section: Integrations
========================================================================

Integrations · Send-through

# Strapi
Send Strapi email through Deckle SMTP.
Use the Strapi nodemailer email provider plugin to send confirmation and reset emails through Deckle.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- Install `@strapi/provider-email-nodemailer` and configure it in plugins config.
- Enter the host, port, username, and the key as the password.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open StrapiConnect Strapi from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/stripe
Section: Integrations
========================================================================

Integrations · Inbound

# Stripe
Turn Stripe customers and subscription events into Deckle contacts and events — for receipts, dunning, and win-back email.
Add Deckle as a Stripe webhook endpoint. New customers become contacts, and payments and cancellations become events that trigger lifecycle automations.

## Set it up

### Connect Stripe in Deckle
Open Integrations → Stripe, click Connect, and copy the endpoint URL and signing secret (shown once).

### Add the endpoint in Stripe
In the Stripe dashboard → Developers → Webhooks, add an endpoint with your Deckle URL. Set its signing secret to your Deckle signing secret, and subscribe to the events below.

## How data maps
Stripe eventBecomes
customer.created / customer.updatedA contact (email + name)
invoice.paidAn invoice.paid event (amount, currency)
customer.subscription.deletedA subscription.canceled event
Signature verification
Stripe signs each request with the stripe-signature header (t=…,v1=…). Deckle verifies the v1 HMAC-SHA256 of {timestamp}.{body} against your signing secret before ingesting.

## Next steps
AutomationsTrigger receipts, dunning, and win-back from Stripe events.
Webhook eventsThe Deckle-side events these map to, and their payloads.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/supabase
Section: Integrations
========================================================================

Integrations · Send-through

# Supabase
Send Supabase Auth emails — confirmations, magic links, password resets — through Deckle for reliable delivery and full logs.
Supabase’s built-in email has strict rate limits and no deliverability tooling. Point Supabase Auth at Deckle’s SMTP relay and every auth email routes through your verified domain on AWS SES, with delivery, bounce, and open tracking in your dashboard.

## Set it up

### Connect Supabase in Deckle
Open Integrations → Supabase and click Connect. Deckle generates a scoped secret key and shows it once — copy it.

### Enable custom SMTP in Supabase
In your Supabase project, go to Authentication → Emails → SMTP Settings and enable Custom SMTP.

### Paste the connection settings
Use the values below. The password is the Deckle key you copied.
SettingValue
Hostsmtp.getdeckle.com
Port587 (STARTTLS)
Usernameapikey
PasswordYour Deckle secret key
Sender emailAn address on your verified domain

### Verify your sender domain
Add and verify the domain you send from under Domains so Supabase mail passes SPF and DKIM. Sends from an unverified domain are rejected.
Keep the key secret
Your SMTP password is a full-access API key. Supabase stores it securely — rotate it any time from the integration page with Regenerate key, which revokes the old one.

## Next steps
API keysHow secret keys work and how Test vs Live maps to your SMTP password.
Domains overviewAdd and verify the domain your Supabase auth emails send from.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/suprsend
Section: Integrations
========================================================================

Integrations · Send-through

# SuprSend
Use Deckle as SuprSend's email vendor.
Add Deckle as an SMTP email vendor in SuprSend so your multi-channel notifications deliver email through your domain.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- In SuprSend → Vendors, add an SMTP email vendor.
- Enter the host, port, username, and the key as the password.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open SuprSendConnect SuprSend from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/trigger-dev
Section: Integrations
========================================================================

Integrations · Send-through

# Trigger.dev
Send email from Trigger.dev jobs via Deckle.
Call the Deckle API from Trigger.dev tasks to send transactional email from your background jobs and workflows.

## Set it up

- Generate a Deckle secret key below and copy it.
- Add it as an environment variable in your Trigger.dev project.
- Call the Deckle API (or SDK) inside a task.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open Trigger.devConnect Trigger.dev from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/twilio
Section: Integrations
========================================================================

Integrations · Bridge

# Twilio
Add SMS steps alongside email in your automations.
Send SMS via Twilio from Deckle automations for multi-channel lifecycle messaging. On the roadmap.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- Connect Twilio to Deckle with Zapier or Make.
- Map records to contacts, or events to automation triggers, and send a test.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open TwilioConnect Twilio from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/typeform
Section: Integrations
========================================================================

Integrations · Inbound

# Typeform
Turn Typeform responses into Deckle contacts and events.
Add Deckle as a Typeform webhook. Each submission upserts a contact (from the email field) and records a `form.submitted` event with the answers.

## Set it up

- Click Connect to generate your endpoint URL and signing secret.
- In Typeform, add a webhook pointed at the endpoint URL and set the signing secret.
- Trigger a test event — the contact or event appears in Deckle within seconds.

## How data maps

- form_response → contact (email answer)
- form_response → event form.submittedRequests are verified via the typeform-signature header using your signing secret.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open TypeformConnect Typeform from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/upstash
Section: Integrations
========================================================================

Integrations · Send-through

# Upstash
Send email from Upstash QStash workflows via Deckle.
Have Upstash QStash call the Deckle API to send email on a schedule or in response to queued events.

## Set it up

- Generate a Deckle secret key below and copy it.
- Store it in your Upstash/QStash environment.
- Publish a QStash message to POST https://app.getdeckle.com/v1/send.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open UpstashConnect Upstash from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/webflow
Section: Integrations
========================================================================

Integrations · Bridge

# Webflow
Sync Webflow form submissions and members into your audience.
Send Webflow form submissions to Deckle via Zapier or Webflow's webhooks to grow your audience and kick off automations.

## Set it up

- Create a Deckle secret key under Developers → API keys and copy it.
- In Webflow, connect your form or record to Zapier (or a webhook).
- Send new leads to Deckle's /v1/contacts so they enter your audience and automations.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open WebflowConnect Webflow from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/woocommerce
Section: Integrations
========================================================================

Integrations · Inbound

# WooCommerce
Sync WooCommerce customers and orders into Deckle.
Add Deckle as a WooCommerce webhook. Customers and orders become contacts and events that power post-purchase and win-back automations.

## Set it up

- Click Connect to generate your endpoint URL and signing secret.
- In WooCommerce, add a webhook pointed at the endpoint URL and set the signing secret.
- Trigger a test event — the contact or event appears in Deckle within seconds.

## How data maps

- customer.created → contact
- order.created → contact + event order.completedRequests are verified via the x-wc-webhook-signature header using your signing secret.

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open WooCommerceConnect WooCommerce from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/wordpress
Section: Integrations
========================================================================

Integrations · Send-through

# WordPress
Route all WordPress site mail through Deckle SMTP with a plugin.
Use an SMTP plugin (WP Mail SMTP, FluentSMTP) to send WordPress transactional and notification email through Deckle.

## Set it up

- Generate a Deckle SMTP key below and copy it.
- Install an SMTP plugin (WP Mail SMTP or FluentSMTP).
- Set the host, port, username, and the key as the password; set From to your verified domain.
- Verify your sender domain under Domains so mail passes SPF and DKIM.

## SMTP settings
SettingValue
Hostsmtp.getdeckle.com
Port587
Usernameapikey
PasswordYour Deckle secret key
Verify your domain
Add and verify your sender domain under Domains so mail passes SPF and DKIM.SMTP settings
```
Host: smtp.getdeckle.com
Port: 587
Username: apikey
Password: <your Deckle secret key>
```

## Related
All integrationsBrowse the full connector catalog and the three integration shapes.
Open WordPressConnect WordPress from your dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/integrations/zapier
Section: Integrations
========================================================================

Integrations · Bridge

# Zapier
Connect Deckle to 8,000+ apps with no code — trigger Zaps from Deckle events and add contacts, record events, or send email as actions.
The Zapier connector bridges Deckle to the rest of your stack. Use Deckle events as Zap triggers, and the Deckle API as Zap actions — all authenticated with a single secret key.

## Set it up

### Connect Zapier in Deckle
Open Integrations → Zapier and click Connect. Deckle generates a secret key for Zapier and shows it once — copy it.

### Add Deckle to your Zap
In Zapier, add the Deckle app and paste the secret key when prompted to authenticate. Then pick a trigger or action below.

## Triggers
Start a Zap when something happens in Deckle:

- contact.created — a new contact is added
- contact.updated / contact.unsubscribed — a contact changes
- event.recorded — a custom event is tracked
- email.delivered / email.bounced — send outcomes

## Actions
ActionAPI
Create or update contactPOST /v1/contacts
Record eventPOST /v1/events
Send emailPOST /v1/send
Prefer to build it yourself?
Every trigger is a Deckle webhook event and every action is a plain REST call. You can wire the same flows directly, or through Make and n8n, without Zapier.

## Next steps
Webhook eventsThe full list of events you can trigger Zaps from, and their payloads.
API referenceThe endpoints behind each Zap action — contacts, events, and sending.


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/introduction
Section: API reference
========================================================================

API reference

# Introduction
The Deckle REST API is organized around resources, uses predictable JSON, and is authenticated with a secret key.
Every dashboard feature is available over HTTP. The API speaks JSON, returns conventional status codes, and is served from a single base URL.

## Base URL
bash
```
https://app.getdeckle.com/api/v1
```
The official Node.js SDK targets this URL by default. All requests must be made over HTTPS.

## Authentication
Authenticate with a secret API key in the Authorization header as a bearer token. Deckle issues secret keys only.

```
curl https://app.getdeckle.com/api/v1/emails \
-H "Authorization: Bearer sk_live_9a8b7c6d..."
```
Keep keys server-side
A secret key can send email and read your data. Never expose it in client-side code. See Authentication.

## Responses
All responses are JSON. Successful requests return a resource object (or, for list endpoints, a data array with cursor metadata). Errors return an error string with an appropriate HTTP status.
json
```
{
"id": "email_9f2c1a8b",
"status": "sent",
"message_id": "0000018f-...-amazonses"
}
```

## Conventions
AuthenticationBearer secret keys, test vs live.

-
- ErrorsStatus codes and the error body shape.
Rate limit120 requests / minute / project.
PaginationCursor-based lists with has_more.
IdempotencySafe retries for sends.


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/authentication
Section: API reference
========================================================================

API reference

# Authentication
Deckle authenticates API requests with a secret key sent as a bearer token.
Deckle issues secret keys only — there are no public or publishable keys, because a send API has no safe client-side scope. Treat every key like a password.

## The Authorization header
Pass your key in the Authorization header. The API rejects requests without a valid secret key with 401 Unauthorized.

```
curl https://app.getdeckle.com/api/v1/contacts \
-H "Authorization: Bearer sk_live_9a8b7c6d..."
```

## Test and live keys
Keys are prefixed by environment: sk_test_ and sk_live_. A test key is sandboxed — it can only send to the AWS SES simulator or your own verified domains, and it cannot run campaign sends. A live key sends to real recipients. Everything else (contacts, templates, automations) behaves the same in both environments, scoped to the same project.
bash
```
sk_test_1f4c... # sandboxed: simulator + verified domains only
sk_live_9a8b... # real inboxes
```

## Managing keys
Create and revoke keys in the dashboard under Developers → API keys. The full key is shown once at creation; Deckle stores only a SHA-256 hash and a masked prefix, so it can never show you the key again. The same secret key is also your SMTP password.
If a key leaks
Revoke it immediately and issue a new one. A leaked key can send email from your verified domains until it’s revoked.


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/errors
Section: API reference
========================================================================

API reference

# Errors
Deckle uses conventional HTTP status codes and returns a JSON error message on every failure.
A 2xx status means success. A 4xx indicates a problem with your request; a 5xx indicates a problem on Deckle’s side.

## Error shape
Every non-2xx response has the same body: a single human-readable message.
json
```
{
"error": "'to' must be a valid email address."
}
```

## Status codes
CodeMeaning
200 / 201Success. Created resources return 201.
202Accepted and queued (for example, an async send or campaign).
400The request body was not valid JSON.
401Missing or invalid secret API key.
403Forbidden — e.g. a test key attempting a live-only action.
404The resource does not exist or is not in your project.
409Conflict — e.g. editing a campaign that has already sent.
422Validation failed. The message names the field or rule.
429Rate limit exceeded. Retry after the Retry-After header.
5xxSomething went wrong on Deckle’s side, or delivery via SES failed (502).

## Handling errors in the SDK
The Node.js SDK throws a DeckleError for any non-2xx response, exposing status, message, and the raw body.
ts
```
import { DeckleError } from "@deckle/sdk";

try {
await deckle.emails.send({ /* … */ });
} catch (err) {
if (err instanceof DeckleError) {
console.error(err.status, err.message);
}
}
```


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/rate-limit
Section: API reference
========================================================================

API reference

# Rate limit
The API allows 120 requests per minute per project.
Rate limits are applied per project, across all endpoints, in a fixed one-minute window. Exceeding the limit returns 429 Too Many Requests.

## The limit
Each project may make 120 requests per minute. When you go over, Deckle responds with 429 and a Retry-After header telling you how many seconds to wait before the window resets.
http
```
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{ "error": "Rate limit exceeded. Slow down and retry shortly." }
```

## Handling 429s
Respect the Retry-After value and back off before retrying. For bursty workloads — importing contacts, sending in batches — spread requests out or add an exponential backoff.
ts
```
async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
try {
return await fn();
} catch (err: any) {
if (err?.status === 429) {
const wait = Number(err.body?.retry_after ?? 2) * 1000;
await new Promise((r) => setTimeout(r, wait));
return withRetry(fn);
}
throw err;
}
}
```
Large audiences
To broadcast to your whole list, use a campaign rather than looping send. Campaigns are delivered by Deckle’s worker and aren’t subject to the per-request API limit.


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/pagination
Section: API reference
========================================================================

API reference

# Pagination
List endpoints are cursor-paginated and return newest-first.
Every list endpoint — emails, contacts, campaigns, templates, automations, suppressions — returns a page of results with a cursor for fetching the next one.

## Query parameters
limitintegerOptionalNumber of items per page. Defaults to 50, clamped between 1 and 100.cursorstringOptionalThe next_cursor from a previous response. Omit it to fetch the first page.

## Response shape
Results come back in a data array with two pagination fields. When has_more is false, next_cursor is null.
json
```
{
"data": [ { "id": "contact_a1", "email": "jane@example.com" } ],
"has_more": true,
"next_cursor": "contact_a1"
}
```

## Paging through everything
Follow the cursor until there are no more pages:
ts
```
let cursor: string | undefined;
const all = [];

do {
const page = await deckle.contacts.list({ limit: 100, cursor });
all.push(...page.data);
cursor = page.next_cursor ?? undefined;
} while (cursor);
```


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/idempotency
Section: API reference
========================================================================

API reference

# Idempotency
Safely retry a send without the risk of delivering it twice.
Network hiccups happen. The send endpoint accepts an idempotency key so a retried request returns the original result instead of sending again.

## The Idempotency-Key header
Send a unique Idempotency-Key header with your request. Reuse the exact same key when you retry. In the SDK, pass idempotencyKey.

```
curl -X POST https://app.getdeckle.com/api/v1/send \
-H "Authorization: Bearer $DECKLE_API_KEY" \
-H "Idempotency-Key: order_1234_receipt" \
-H "Content-Type: application/json" \
-d '{ "from": "Acme <hello@acme.com>", "to": "jane@example.com",
"subject": "Receipt", "html": "<p>Thanks!</p>" }'
```

## Behavior
The first request with a given key sends the email and records the result. Any later request with the same key — for this project — skips sending and returns the original result with idempotent: true and a 200 status.
json
```
{
"id": "email_9f2c1a8b",
"status": "sent",
"messageId": "0000018f-...-amazonses",
"idempotent": true
}
```
Choosing a key
Derive the key from the business action, not the moment — for example order_1234_receipt or user_42_welcome. That way an accidental double-fire of the same logical event is de-duplicated, while genuinely different emails still send.


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/emails
Section: API reference
========================================================================

API reference

# Emails
Send transactional email and inspect what was sent.
The emails resource sends a single message and lets you look up its delivery, open, and click status afterward. All requests are authenticated with a secret key.

## The email object
json
```
{
"id": "email_9f2c1a8b",
"to": "jane@example.com",
"subject": "Welcome to Acme",
"type": "transactional",
"status": "delivered",
"message_id": "0000018f-4c2a-...-amazonses",
"opens": 1,
"clicks": 0,
"created_at": "2026-07-10T14:23:45.123Z"
}
```

## Send an email
POST/v1/sendProvide either html or a stored template. The from address must be on a verified domain. Supports an optional Idempotency-Key header for safe retries.
Body parameters
fromstringRequiredSender address. Accepts "Name <addr@domain>" or a bare address. The domain must be verified for your project.tostringRequiredRecipient email address.subjectstringRequiredSubject line. Supports {{variables}} when sending a template.htmlstringOptionalHTML body. Required unless template is provided.templatestringOptionalA stored template id to render instead of html.textstringOptionalPlain-text alternative. Auto-generated for template sends if omitted.variablesobjectOptionalValues substituted into the template and subject, e.g. { "first_name": "Jane" }.ccstring | string[]OptionalCarbon-copy recipient(s). Invalid addresses are dropped.bccstring | string[]OptionalBlind carbon-copy recipient(s).reply_tostring | string[]OptionalReply-To address(es).attachmentsobject[]OptionalFiles to attach — each { filename, content, content_type? } with content base64-encoded. See Attachments.
```
curl -X POST https://app.getdeckle.com/api/v1/send \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: order_1234" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <hello@acme.com>",
"to": "jane@example.com",
"subject": "Welcome to Acme",
"html": "<h1>Hey Jane</h1>"
}'
```
Statuses
200 with status: "sent" on success. If delivery isn’t configured yet you get 202 with status: "queued". Validation errors return 422; a test key sending to a real inbox returns 403; a suppressed recipient returns 422.

## List emails
GET/v1/emailsReturns a cursor-paginated list of sent emails, newest first.
Query parameters
limitintegerOptionalItems per page. Default 50, max 100.cursorstringOptionalPagination cursor from a previous next_cursor.statusstringOptionalFilter by status, e.g. sent, delivered, failed.typestringOptionalFilter by type, e.g. transactional, campaign.ts
```
const { data, has_more, next_cursor } = await deckle.emails.list({
status: "sent",
limit: 50,
});
```

## Retrieve an email
GET/v1/emails/:idFetch a single email with its current status and open/click counts.

```
const email = await deckle.emails.get("email_9f2c1a8b");
```
A missing or cross-project id returns 404.


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/contacts
Section: API reference
========================================================================

API reference

# Contacts
Create, read, update, and delete the contacts in your audience.
A contact is an email address plus optional profile and custom data. Contacts are unlimited — Deckle bills on sends, not audience size.

## The contact object
json
```
{
"id": "contact_a1b2c3",
"email": "jane@example.com",
"name": "Jane Doe",
"subscribed": true,
"source": "api",
"data": { "plan": "pro" },
"created_at": "2026-07-10T10:30:00.000Z",
"updated_at": "2026-07-10T10:30:00.000Z"
}
```

## Create or update a contact
POST/v1/contactsUpserts by email. A new email returns 201; an existing one is updated and returns 200. Omitted fields are left unchanged on update.
Body parameters
emailstringRequiredThe contact’s email address. Normalized to lowercase.namestringOptionalDisplay name. An empty string is stored as null.subscribedbooleanOptionalSubscription state. Defaults to true on create.sourcestringOptionalWhere the contact came from. Defaults to api on create.dataobjectOptionalArbitrary custom fields as a JSON object (not an array), e.g. { "plan": "pro" }.
```
curl -X POST https://app.getdeckle.com/api/v1/contacts \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "email": "jane@example.com", "name": "Jane Doe",
"data": { "plan": "pro" } }'
```
Automation enrollment
A newly-created subscribed contact is automatically enrolled in any live automation triggered by contact.subscribed.

## List contacts
GET/v1/contactsQuery parameters
limitintegerOptionalItems per page. Default 50, max 100.cursorstringOptionalPagination cursor.emailstringOptionalFilter by exact email address.subscribedbooleanOptionalFilter by subscription state (true or false).ts
```
const { data, has_more, next_cursor } = await deckle.contacts.list({ limit: 50 });
```

## Retrieve a contact
GET/v1/contacts/:idts
```
const contact = await deckle.contacts.get("contact_a1b2c3");
```

## Update a contact
PATCH/v1/contacts/:idPartial update — only the fields you send change. The email address cannot be changed via PATCH.
ts
```
await deckle.contacts.update("contact_a1b2c3", {
subscribed: false,
data: { plan: "free" },
});
```

## Delete a contact
DELETE/v1/contacts/:id
```
await deckle.contacts.delete("contact_a1b2c3");
```


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/events
Section: API reference
========================================================================

API reference

# Events
Record custom events to power contact timelines and trigger automations.
An event is a named action, optionally tied to a contact by email — like user.signed_up or order.completed. Events are the trigger primitive behind automations.

## The event object
json
```
{
"id": "event_7x8y9z",
"name": "user.signed_up",
"contact_id": "contact_a1b2c3",
"created_at": "2026-07-10T10:30:45.123Z"
}
```

## Record an event
POST/v1/eventsIf email matches a known contact, the event is linked to it. If the email is unknown the event is still recorded, with contact_id set to null.
Body parameters
namestringRequiredThe event name, e.g. order.completed.emailstringOptionalEmail of the contact to attribute the event to.dataobjectOptionalArbitrary JSON payload for the event, e.g. { "amount": 4900, "currency": "usd" }.
```
curl -X POST https://app.getdeckle.com/api/v1/events \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "name": "order.completed", "email": "jane@example.com",
"data": { "amount": 4900 } }'
```
Events drive automations
Recording an event enrolls the matching contact into any live automation triggered by that event, and wakes any automation runs that are waiting for it. A missing name returns 422.


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/suppressions
Section: API reference
========================================================================

API reference

# Suppressions
Manage the list of addresses Deckle will never send to.
Deckle automatically suppresses hard bounces and complaints. You can inspect the list and add or remove addresses yourself. A send to a suppressed address is rejected with 422.

## The suppression object
json
```
{
"email": "bounced@example.com",
"reason": "hard_bounce",
"created_at": "2026-07-10T10:30:00.000Z"
}
```
reason is one of hard_bounce, complaint, unsubscribe, or manual.

## List suppressions
GET/v1/suppressionsQuery parameters
limitintegerOptionalItems per page. Default 50, max 100.cursorstringOptionalPagination cursor.ts
```
const { data, has_more, next_cursor } = await deckle.suppressions.list({ limit: 100 });
```

## Add a suppression
POST/v1/suppressionsIdempotent by email. A new address returns 201; an existing one returns 200 unchanged.
Body parameters
emailstringRequiredAddress to suppress. Normalized to lowercase.reasonstringOptionalWhy it’s suppressed. Defaults to manual.
```
curl -X POST https://app.getdeckle.com/api/v1/suppressions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "email": "bounced@example.com", "reason": "manual" }'
```

## Remove a suppression
DELETE/v1/suppressions/:emailThe email in the path must be URL-encoded. Removing a suppression lets you send to that address again.

```
await deckle.suppressions.delete("bounced@example.com");
```
A missing address returns 404. See the deliverability guide for why suppression matters.


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/campaigns
Section: API reference
========================================================================

API reference

# Campaigns
Create, target, and send broadcast campaigns to your whole list or a segment.
A campaign is a one-off broadcast built from a template. Create it as a draft, then send it. Campaign sends require a live key.

## The campaign object
json
```
{
"id": "camp_x1y2z3",
"name": "March newsletter",
"subject": "What's new this month",
"preview_text": "A quick roundup",
"from_name": "Acme",
"from_email": "news@acme.com",
"target": "all",
"template": "tmpl_123",
"segment": null,
"status": "draft",
"stats": null,
"variants": [{ "id": "B", "subject": "You missed a lot" }],
"scheduled_at": null,
"sent_at": null,
"created_at": "2026-07-10T10:30:00.000Z",
"updated_at": "2026-07-10T10:30:00.000Z"
}
```
status moves through draft → queued → sending → sent. target is all or segment.

## Create a campaign
POST/v1/campaignsCreates a draft. The from_email domain must be verified.
Body parameters
namestringRequiredInternal name for the campaign.subjectstringRequiredSubject line (variant A).from_namestringRequiredSender display name.from_emailstringRequiredSender address on a verified domain.preview_textstringOptionalInbox preview / preheader text.templatestringOptionalThe template id to send. Required before the campaign can be sent.target"all" | "segment"OptionalWho to send to. Defaults to all.segmentstringOptionalSegment id — required when target is segment.variantsstring[]OptionalUp to three alternate subject lines for A/B testing. The base subject is variant A; extras become B, C, and D.
```
const campaign = await deckle.campaigns.create({
name: "March newsletter",
subject: "What's new this month",
from_name: "Acme",
from_email: "news@acme.com",
template: "tmpl_123",
target: "all",
variants: ["You missed a lot"],
});
```

## List campaigns
GET/v1/campaignsQuery parameters
limitintegerOptionalItems per page. Default 50, max 100.cursorstringOptionalPagination cursor.statusstringOptionalFilter by status, e.g. draft or sent.ts
```
const { data } = await deckle.campaigns.list({ status: "sent" });
```

## Retrieve a campaign
GET/v1/campaigns/:idts
```
const campaign = await deckle.campaigns.get("camp_x1y2z3");
```

## Update a campaign
PATCH/v1/campaigns/:idOnly a draft campaign can be edited — updating one that’s already sending or sent returns 409. Send any of name, subject, from_name, from_email, preview_text, template, target, or segment.
bash
```
curl -X PATCH https://app.getdeckle.com/api/v1/campaigns/camp_x1y2z3 \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "subject": "A better subject" }'
```

## Send a campaign
POST/v1/campaigns/:id/sendSends the campaign now. The campaign must have a template. When the background worker is configured the send is queued and returns 202 with queued: true; otherwise it runs inline (capped at 200 recipients) and returns the counts.

```
const result = await deckle.campaigns.send("camp_x1y2z3");
// queued: { ...campaign, queued: true }
// sync: { ...campaign, sent: 184, failed: 0 }
```
Live key required
A test key can’t send campaigns and returns 403. Sending a campaign with no template returns 422; re-sending one that’s already sending returns 409.


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/templates
Section: API reference
========================================================================

API reference

# Templates
Create and read reusable email templates, and browse the shared gallery.
Templates store a subject and design you can send by id. Send one by passing template to the send endpoint.

## The template object
json
```
{
"id": "tmpl_123",
"name": "Welcome",
"category": "Onboarding",
"subject": "Welcome, {{first_name}}",
"source": "<html>…</html>",
"format": "html",
"is_system": false,
"created_at": "2026-07-10T10:30:00.000Z",
"updated_at": "2026-07-10T10:30:00.000Z"
}
```
is_system is true for shared gallery templates, which are read-only.

## List templates
GET/v1/templatesQuery parameters
limitintegerOptionalItems per page. Default 50, max 100.cursorstringOptionalPagination cursor.scopestringOptionalPass all to include the shared system gallery alongside your templates.categorystringOptionalFilter by category, e.g. Onboarding or Transactional.ts
```
const { data } = await deckle.templates.list({ scope: "all" });
```

## Create a template
POST/v1/templatesBody parameters
namestringRequiredTemplate name.subjectstringOptionalSubject line. Defaults to the name if omitted.categorystringOptionalCategory label. Defaults to the first valid category.sourcestringOptionalThe template body — HTML or serialized blocks.format"html" | "blocks"OptionalHow source is interpreted. Defaults to blocks.
```
const tmpl = await deckle.templates.create({
name: "Welcome",
subject: "Welcome, {{first_name}}",
category: "Onboarding",
source: "<h1>Welcome aboard!</h1>",
});
```

## Retrieve a template
GET/v1/templates/:idWorks for both your templates and read-only system gallery templates.
ts
```
const tmpl = await deckle.templates.get("tmpl_123");
```

## Update a template
PATCH/v1/templates/:idUpdate name, category, subject, source, or format.
bash
```
curl -X PATCH https://app.getdeckle.com/api/v1/templates/tmpl_123 \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "subject": "Welcome to Acme, {{first_name}}" }'
```
Gallery templates are read-only
System templates (is_system: true) can’t be edited — a PATCH to one returns 404. Duplicate it into your project first from the dashboard.


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/automations
Section: API reference
========================================================================

API reference

# Automations
Create and manage event-driven workflows: a trigger plus an ordered graph of steps.
An automation is a trigger and a list of steps that form a forward-only graph. New automations start as draft; set them live to run.

## The automation object
json
```
{
"id": "auto_9k8j7h",
"name": "Welcome series",
"status": "live",
"trigger": { "event": "contact.subscribed" },
"steps": [
{ "id": "step-0", "type": "email", "detail": "Welcome",
"templateId": "tmpl_123", "next": "step-1" },
{ "id": "step-1", "type": "delay", "delayMinutes": 1440, "next": null }
],
"step_count": 2,
"created_at": "2026-07-10T10:30:00.000Z",
"updated_at": "2026-07-10T10:30:00.000Z"
}
```

## Triggers
A trigger is one of:
json
```
{ "event": "contact.subscribed" }
{ "event": "event", "name": "order.completed" }
```

## Step types
typeKey fieldsWhat it does
emailtemplateId, subjectOverride?Sends a template to the enrolled contact.
delaydelayMinutes (1–525600)Waits a fixed amount of time.
waitwaitEvent, waitTimeoutMinutes (1–36000)Pauses until an event arrives or the timeout elapses.
branchbranchCondition, nextTrue, nextFalseTwo-way if/else on a field, operator, and value.
actionaction, actionKey?, actionValue?, tag?unsubscribe, update-field, add-tag, or remove-tag.
Every step has an id (unique) and an optional next pointer. Omit next to fall through to the following step; set it to null to end the run. Pointers must move forward — backward or dangling references are dropped.

## List automations
GET/v1/automationsQuery parameters
limitintegerOptionalItems per page. Default 50, max 100.cursorstringOptionalPagination cursor.status"draft" | "live"OptionalFilter by status.ts
```
const { data } = await deckle.automations.list({ status: "live" });
```

## Create an automation
POST/v1/automationsBody parameters
namestringRequiredName, up to 120 characters.triggerobjectOptionalTrigger config. Defaults to { "event": "contact.subscribed" }.stepsobject[]OptionalOrdered steps. Ids must be unique; missing ids are generated.
```
const automation = await deckle.automations.create({
name: "Welcome series",
trigger: { event: "contact.subscribed" },
steps: [
{ id: "step-0", type: "email", detail: "Welcome", templateId: "tmpl_123" },
{ id: "step-1", type: "delay", detail: "", delayMinutes: 1440 },
],
});
```

## Retrieve an automation
GET/v1/automations/:idts
```
const automation = await deckle.automations.get("auto_9k8j7h");
```

## Update an automation
PATCH/v1/automations/:idUpdate name, trigger, steps, or status.
ts
```
// Turn it on — resumes any paused enrollments.
await deckle.automations.update("auto_9k8j7h", { status: "live" });
```
Going live
Setting status to live resumes paused enrollments. An invalid status or duplicate step ids return 422.

## Delete an automation
DELETE/v1/automations/:id
```
await deckle.automations.delete("auto_9k8j7h");
```


========================================================================
URL: https://app.getdeckle.com/docs/api-reference/webhook-events
Section: API reference
========================================================================

API reference

# Webhook events
The payloads Deckle delivers to your registered webhook endpoints.
When something happens to an email you sent, Deckle POSTs a signed event to every active webhook endpoint subscribed to that event type.

## Request format
Every delivery is an HTTP POST with a JSON body and two headers: X-Deckle-Event (the event type) and X-Deckle-Signature (an HMAC-SHA256 hex digest of the raw body — see Verifying signatures).
http
```
POST /your/webhook HTTP/1.1
Content-Type: application/json
X-Deckle-Event: email.delivered
X-Deckle-Signature: 3f9a1c...e7
```

## Envelope
Every event shares the same top-level shape:
json
```
{
"type": "email.delivered",
"created_at": "2026-07-10T14:23:45.123Z",
"data": { }
}
```

## Event types
typeFired when
email.deliveredThe receiving mail server accepted the message.
email.bouncedA hard bounce. The address is also added to your suppression list.
email.complainedThe recipient marked it as spam. The address is suppressed.
email.openedThe tracking pixel was loaded.
email.clickedA tracked link was clicked.

## The data object
The data object identifies the email the event is about — its id, recipient, and subject — plus fields specific to the event.

### email.delivered / opened
json
```
{
"type": "email.opened",
"created_at": "2026-07-10T14:25:00.000Z",
"data": {
"id": "email_9f2c1a8b",
"to": "jane@example.com",
"subject": "Welcome to Acme"
}
}
```

### email.clicked
Click events also include the url that was followed.
json
```
{
"type": "email.clicked",
"created_at": "2026-07-10T14:26:10.000Z",
"data": {
"id": "email_9f2c1a8b",
"to": "jane@example.com",
"subject": "Welcome to Acme",
"url": "https://acme.com/get-started"
}
}
```

### email.bounced / complained
json
```
{
"type": "email.bounced",
"created_at": "2026-07-10T14:24:30.000Z",
"data": {
"id": "email_9f2c1a8b",
"to": "jane@example.com",
"subject": "Welcome to Acme",
"reason": "hard_bounce"
}
}
```
Always respond 2xx quickly
Acknowledge the webhook with a 2xx status as soon as you’ve verified the signature, then do slow work asynchronously. Verify the signature against the raw body before trusting any field.


========================================================================
URL: https://app.getdeckle.com/docs/sdks/node
Section: SDKs
========================================================================

SDKs

# Node.js SDK
The official @deckle/sdk package — a thin, fully typed wrapper over the Deckle REST API for sending email and managing your audience.
@deckle/sdk gives you a typed client for every Deckle resource. It has zero dependencies, ships with TypeScript types out of the box, and runs anywhere modern fetch is available.
Runtime support
The SDK targets Node 18+ and also runs on Deno, Bun, and the browser. It relies only on the built-in fetch, so there is nothing else to install.

## Install
Add the package to your project with your package manager of choice.
bash
```
npm install @deckle/sdk
```

## Initialize
Create a client with a secret API key. Keep the key in an environment variable — never commit it to source control. Generate one in the dashboard under Developers → API keys.
deckle.ts
```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

const { id } = await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Welcome to Acme 👋",
html: "<h1>Hey Jane</h1><p>Thanks for joining.</p>",
});

console.log("Sent", id);
```
Test vs. live
A sk_test_ key only delivers to the SES simulator or your own verified domains, so you can wire up the SDK safely before going live. Swap in a sk_live_ key to send to real inboxes.

## Resources
Every REST resource is exposed as a namespace on the client. Method names map directly to the underlying API, and all inputs and responses are fully typed.
ResourceMethods
deckle.emailssend, get, list
deckle.contactscreate, list, get, update, delete
deckle.eventscreate
deckle.suppressionslist, create, delete
deckle.campaignscreate, list, get, send
deckle.templatescreate, list, get
deckle.automationscreate, list, get, update, delete
Here are a few of them in context — send an email, upsert a contact, and record an event.
usage.ts
```
// Send a transactional email
await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "jane@example.com",
subject: "Your receipt",
template: "tmpl_receipt",
variables: { order_id: "order_1234", total: "$49.00" },
});

// Upsert a contact by email
await deckle.contacts.create({
email: "jane@example.com",
name: "Jane Doe",
data: { plan: "pro" },
});

// Record an event that can trigger an automation
await deckle.events.create({
name: "order.completed",
email: "jane@example.com",
data: { order_id: "order_1234" },
});
```
List endpoints are cursor-based and return { data, has_more, next_cursor }. Pass limit and cursor to page through results.
ts
```
let cursor: string | null = null;

do {
const page = await deckle.emails.list({ limit: 100, cursor });
for (const email of page.data) {
console.log(email.id, email.status);
}
cursor = page.next_cursor;
} while (cursor);
```

## Handling errors
Any non-2xx response throws a DeckleError. It exposes the HTTP status, a human-readable message, and the parsed response body (the { error } payload) so you can branch on the exact failure.
errors.ts
```
import { Deckle, DeckleError } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!);

try {
await deckle.emails.send({
from: "Acme <hello@acme.com>",
to: "suppressed@example.com",
subject: "Hello",
html: "<p>Hi</p>",
});
} catch (err) {
if (err instanceof DeckleError) {
console.error(err.status); // e.g. 422
console.error(err.message); // "Recipient is suppressed"
console.error(err.body); // { error: "Recipient is suppressed" }
} else {
throw err;
}
}
```
Rate limits
A burst past 120 requests / minute throws a DeckleError with status 429. Read the Retry-After header (in seconds) from the response and back off before retrying.

## Verify webhooks
Deckle signs every webhook delivery with HMAC-SHA256 over the raw request body. Use the verifyWebhookSignature helper to confirm a payload really came from Deckle before you trust it. Pass the raw body string — not a re-serialized object — along with the X-Deckle-Signature header and your endpoint's whsec_ secret.
webhook.ts
```
import { verifyWebhookSignature } from "@deckle/sdk";

// e.g. an Express route mounted with a raw body parser
app.post("/webhooks/deckle", (req, res) => {
const signature = req.header("X-Deckle-Signature")!;
const valid = verifyWebhookSignature(
req.body, // the raw request body
signature,
process.env.DECKLE_WEBHOOK_SECRET!,
);

if (!valid) {
return res.status(400).send("Invalid signature");
}

const event = JSON.parse(req.body);
console.log(event.type); // "email.delivered", "email.opened", ...
res.sendStatus(200);
});
```
Raw body required
The signature is computed over the exact bytes Deckle sent. Verify against the raw body before any JSON parsing or middleware re-encodes it. See Verify webhooks for framework-specific setup.

## Options
The constructor accepts an optional second argument. Override baseUrl to point at a different host, or pass a custom fetch implementation to add retries, logging, or proxying.
ts
```
import { Deckle } from "@deckle/sdk";

const deckle = new Deckle(process.env.DECKLE_API_KEY!, {
baseUrl: "https://app.getdeckle.com/api/v1",
fetch: customFetch, // your own fetch-compatible function
});
```

## Next steps
Send with the SDKTemplates, variables, attachments, and idempotency with deckle.emails.send.
API referenceEvery endpoint, parameter, and response behind the SDK methods.