DeckleDocs
Dashboard

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/send

Provide 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

fromstringRequired
Sender address. Accepts "Name <addr@domain>" or a bare address. The domain must be verified for your project.
tostringRequired
Recipient email address.
subjectstringRequired
Subject line. Supports {{variables}} when sending a template.
htmlstringOptional
HTML body. Required unless template is provided.
templatestringOptional
A stored template id to render instead of html.
textstringOptional
Plain-text alternative. Auto-generated for template sends if omitted.
variablesobjectOptional
Values substituted into the template and subject, e.g. { "first_name": "Jane" }.
ccstring | string[]Optional
Carbon-copy recipient(s). Invalid addresses are dropped.
bccstring | string[]Optional
Blind carbon-copy recipient(s).
reply_tostring | string[]Optional
Reply-To address(es).
attachmentsobject[]Optional
Files 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/emails

Returns a cursor-paginated list of sent emails, newest first.

Query parameters

limitintegerOptional
Items per page. Default 50, max 100.
cursorstringOptional
Pagination cursor from a previous next_cursor.
statusstringOptional
Filter by status, e.g. sent, delivered, failed.
typestringOptional
Filter 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/:id

Fetch 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.