Truncus Email

Truncus is a transactional email API for delivering alerts, reports, receipts, and notifications. EU-native infrastructure (AWS SES eu-west-1), deterministic delivery with idempotency enforcement and full event tracing.

When to Use

Use this skill when a workflow needs to send email: system alerts, generated reports, order receipts, password resets, onboarding sequences, monitoring notifications, or any programmatic email delivery.

Authentication

Truncus uses Bearer token authentication. The API key is read from the TRUNCUS_API_KEY environment variable.

Header format:

CODEBLOCK0

API keys use the prefix tr_live_ followed by 64 hex characters. If the key is missing, malformed, or revoked, the API returns HTTP 401 with an error code (MISSING_API_KEY, INVALID_API_KEY, or API_KEY_REVOKED).

Send Endpoint

CODEBLOCK1

Required Headers

Header	Value	Required
INLINECODE5	INLINECODE6	Yes
INLINECODE7

Unique string per send attempt | Yes | | Content-Type | application/json | Yes |

The Idempotency-Key header is mandatory. Requests without it receive HTTP 400 with code MISSING_IDEMPOTENCY_KEY. If a duplicate key is submitted, the API returns the original message without re-sending (status duplicate).

Required Body Fields

Field	Type	Description
INLINECODE13	string	Recipient email address (single address)
INLINECODE14

string | Sender address (must be a verified domain) | | subject | string | Email subject line (non-empty) |

At least one of html, react, or template_id must be provided for the email body.

Field	Type	Description
INLINECODE19	string	HTML body (max 256KB)
INLINECODE20

string | React Email JSX template (max 64KB) |
| template_id | string | Server-side template ID |

Optional Body Fields

Field	Type	Description
INLINECODE22	string	Plain text fallback (max 128KB)
INLINECODE23

string[] | CC recipients | | bcc | string[] | BCC recipients | | variables | object | Template variable substitution (handlebars-style) | | metadata | object | Arbitrary key-value metadata stored with the email | | tenant_id | string | Multi-tenant isolation identifier | | attachments | Attachment[] | Up to 10 attachments, total max 10MB | | send_at | string (ISO 8601) | Schedule send for a future datetime (must be future) | | track_opens | boolean | Enable open tracking pixel (default: true) | | track_clicks | boolean | Enable click tracking rewrites (default: true) |

Attachment object:

CODEBLOCK2

Request Example

CODEBLOCK3

Response Handling

Success (HTTP 200)

CODEBLOCK4

Scheduled (HTTP 200)

When send_at is provided:

CODEBLOCK5

Duplicate (HTTP 200)

When the same Idempotency-Key is reused:

CODEBLOCK6

Queued with Retry (HTTP 200)

On transient provider errors:

CODEBLOCK7

Validation Error (HTTP 400)

CODEBLOCK8

Domain Error (HTTP 400)

CODEBLOCK9

Suppressed (HTTP 200)

All recipients on suppression list:

CODEBLOCK10

Provider Failure (HTTP 502)

CODEBLOCK11

Authentication Error (HTTP 401)

CODEBLOCK12

Scope Error (HTTP 403)

CODEBLOCK13

Rate Limiting

Truncus enforces three layers of rate limiting:

1. 1. Burst limit: 10 requests/second, 60 requests/minute per API key
2. Monthly plan cap: Free = 3,000, Pro = 25,000, Scale = 250,000 emails/month
3. Domain daily cap: per-domain warmup limits

When rate limited, the API returns HTTP 429 with these headers:

Header	Description
INLINECODE36	Maximum requests per minute (60)
INLINECODE37

Requests remaining in current window |
| X-RateLimit-Reset | Unix timestamp when window resets |
| Retry-After | Seconds to wait before retrying |

Monthly usage headers are included on every successful response:

Header	Description
INLINECODE40	Monthly email quota
INLINECODE41

Emails sent this billing month |
| X-Monthly-Remaining| Emails remaining this month |

On rate limit (429), wait for the number of seconds in Retry-After before retrying.

Get Email Details

CODEBLOCK14

Requires the read_events scope. Returns the email with its full event timeline:

CODEBLOCK15

Cancel Scheduled Email

CODEBLOCK16

Requires the send scope. Only emails with status scheduled can be cancelled. Returns HTTP 409 if the email is in any other state.

CODEBLOCK17

Sandbox Mode

Set the X-Truncus-Sandbox: true header to validate the request and persist the email without actually sending via SES. Useful for testing integrations. Sandbox emails receive a sandbox- prefixed provider message ID.

CODEBLOCK18

Response includes "sandbox": true.

Local Dev Mode

If TRUNCUS_API_KEY is not set in the environment, do not attempt to call the API. Instead:

1. 1. Print the full request payload that would be sent (to, from, subject, body preview).
2. Log: INLINECODE51
3. Return a simulated success with message_id: "local-simulated".
4. Direct the user to https://truncus.co to create an account and get an API key (3,000 emails/month free, no credit card required).

Safety Rules

1. 1. Never send email unless the user explicitly asks. Do not send as a side effect of another action.
2. Confirm recipients before sending. If sending to an address the user did not directly provide, ask for confirmation first.
3. Always use a unique Idempotency-Key. Generate a UUID for each send attempt. Never reuse keys across different emails.
4. Never fabricate a success response. If the API call fails or is simulated, report it honestly.
5. Do not send to large recipient lists. Truncus accepts a single to address per request. For bulk sends, confirm the intent and send individual requests.
6. Respect suppression. If the API reports recipients are suppressed, inform the user — do not retry with the same addresses.
7. Handle rate limits gracefully. On 429, wait for the Retry-After duration, then retry once. Report the limit to the user if it persists.