Docs
Let your AI assistant set up Irisend.
Copy the prompt below and paste it into Claude Code, Cursor, Copilot, or any chat assistant working in your codebase. It carries the full API reference and step-by-step instructions, so the assistant can add a send helper, env config, and webhook verification without you reading the docs first.
Promptmarkdown
You are helping me add Irisend (a transactional email API) to this project. Everything you need is in the reference below — don't guess endpoints or fields that aren't in it.
Do this:
1. Look at the codebase and figure out the language, framework, and how config/secrets are loaded. If there is already an email provider (Resend, SendGrid, Postmark, Nodemailer, ...), tell me and ask whether to replace it before touching it.
2. Add `IRISEND_API_KEY` to the project's env config (and to `.env.example` with a placeholder, never a real key). Ask me for the `from` address; it must be on a domain I have verified in Irisend.
3. Create one small, typed email helper/module (e.g. `sendEmail({ to, subject, html, text })`) that sends via `POST https://api.irisend.com/emails`. If this is a Node/TypeScript project, install `@irisend/sdk` (`npm install @irisend/sdk`) and use its `emails.send` — it returns `{ data, error }` and never throws. Otherwise use the project's existing HTTP client (Python/PHP SDKs exist but aren't registry-published yet, so prefer plain HTTP there unless I ask for the SDK specifically). It must:
- send `Authorization: Bearer $IRISEND_API_KEY` and `Content-Type: application/json`;
- accept an optional idempotency key and send it as `Idempotency-Key`;
- on failure, surface the error `name` and `message` from the JSON body;
- retry only on 429 (honouring `retry-after`) and 5xx, with the same idempotency key.
4. Wire it into the place I point you to (or the most obvious existing email trigger), and show me how to send a test email.
5. Only if I ask for delivery tracking: add a webhook endpoint that verifies the signature as shown below, using the raw request body, and store the secret as `IRISEND_WEBHOOK_SECRET`.
Keep changes minimal and match the project's existing style. When you're done, list the files you changed and the env vars I need to set.
---
# Irisend
> Irisend is a developer-first email API for transactional and marketing email, built on AWS SES. It is a plain REST API over HTTPS with JSON bodies, modelled on the Resend API (same request/response shapes, snake_case fields).
## Basics
- Base URL: `https://api.irisend.com`
- Auth: `Authorization: Bearer <API key>` on every request. Keys look like `ir_<8 chars>_<30 chars>` (the last 6 characters are a checksum). Read the key from the `IRISEND_API_KEY` environment variable; never hardcode or commit it.
- Content type: `Content-Type: application/json` on every request with a body.
- SDKs: `@irisend/sdk` is published on npm for Node.js (`npm install @irisend/sdk`; same `{ data, error }` shape as the `resend` package). Python (`irisend`) and PHP (`irisend/irisend-php`) SDKs exist but aren't published to a registry yet — install them from the repo (see /docs/sdk-python / /docs/sdk-php) or just use the language's standard HTTP client (`requests` in Python, `curl`/`Guzzle` in PHP, `net/http` in Go, etc.) against the REST API directly.
- Key permissions: `full_access` (every endpoint) or `sending_access` (only `POST /emails` and `POST /emails/batch`). A key scoped to a domain can only send from that domain. Use a `sending_access` key in application code that only sends.
## Before the first send
1. The user creates an account at Irisend and an API key in the dashboard (Configuration → API keys). The token is shown once.
2. The `from` address must be on a verified domain. `POST /domains` with `{ "name": "yourdomain.com" }` returns DNS records (DKIM TXT, SPF MX + TXT on the `send` subdomain, optional DMARC TXT) that the user must add at their DNS provider. Then `POST /domains/:id/verify` or poll `GET /domains/:id` until `status` is `verified`. Sending from an unverified domain fails with 403 `validation_error`.
## Send an email — POST /emails
```bash
curl -X POST https://api.irisend.com/emails \
-H "Authorization: Bearer $IRISEND_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-8841-receipt" \
-d '{
"from": "Acme <[email protected]>",
"to": ["[email protected]"],
"subject": "Your receipt",
"html": "<p>Thanks for your order.</p>",
"text": "Thanks for your order."
}'
```
Response: `{ "id": "em_9f2K3mQ1zPr7vT6yB4wL0nC" }`
Body fields:
- `from` (required): `[email protected]` or `Name <[email protected]>`, on a verified domain.
- `to` (required), `cc`, `bcc`, `reply_to`: a string or an array of up to 50 addresses.
- `subject` (required): 1–998 characters.
- `html` and/or `text`: at least one is required.
- `headers`: object of extra string headers.
- `tags`: up to 50 `{ "name", "value" }` objects; both only ASCII letters, digits, `_` or `-`, max 256 chars.
- `attachments`: up to 20 `{ "filename", "content" (base64) | "path" (URL), "content_type"?, "content_id"? }` — exactly one of `content` or `path`.
- `react` (Node.js SDK only): pass a React element instead of `html` — `irisend.emails.send({ ..., react: <Welcome /> })`. Takes precedence over `html` when both are given; requires the optional peer dependency `@react-email/render` (`npm install @react-email/render react react-dom`), lazily imported so it's only needed if you actually pass `react`.
- `scheduled_at`: ISO 8601 timestamp with offset, to send later.
Header `Idempotency-Key` (1–256 chars): reusing a key returns the original email without re-sending. Generate one per logical send (e.g. per order/user action), never a constant. Keys are team-scoped and currently don't expire.
## Other email endpoints
- `POST /emails/batch` — body is a JSON array of 1–100 email objects shaped like `POST /emails`. Response `{ "data": [{ "id" }, ...] }` in input order. Counts as one request for rate limiting.
- `GET /emails/:id` — returns `{ object: "email", id, to, from, subject, html, text, cc, bcc, reply_to, created_at, scheduled_at, last_event, tags }`. `last_event` is the latest status (e.g. `sent`, `delivered`, `bounced`).
- `PATCH /emails/:id` — body `{ "scheduled_at": "..." }`; only while the email is still scheduled. Response `{ object: "email", id }`.
- `POST /emails/:id/cancel` — cancels a scheduled email. Response `{ object: "email", id }`.
## Domains
- `POST /domains` — `{ "name": "yourdomain.com", "region"?: "eu-west-1", "capabilities"?: { "sending"?: "enabled", "receiving"?: "enabled" | "disabled" } }`. Returns `{ object: "domain", id, name, status, region, capabilities: { sending, receiving }, open_tracking, click_tracking, tls, records: [{ record, type, name, value, priority?, ttl, status, required }] }`.
- `GET /domains` (list, no records), `GET /domains/:id` (with records), `POST /domains/:id/verify` (re-check DNS now).
- `PATCH /domains/:id` — `open_tracking`, `click_tracking` (booleans), `tls` (`opportunistic` | `enforced`), `capabilities` (same shape as create; at least one of `sending`/`receiving` must stay enabled).
- `DELETE /domains/:id` — returns `{ object, id, deleted: true }`.
## Receiving emails
- Off by default. Enable with `capabilities.receiving: "enabled"` on `POST /domains` or `PATCH /domains/:id`; the response then includes a `RECEIVING` MX record (`@` → `inbound-smtp.<region>.amazonaws.com`, priority 10) to add at the domain's DNS provider — use a subdomain instead if the apex already has an MX record.
- `GET /emails/receiving` (list), `GET /emails/receiving/:id?html_format=data_uri|cid` (full email incl. `html`, `text`, `headers`, `authentication`, and a 1-hour signed `raw.download_url` for the original MIME file).
- `GET /emails/receiving/:id/attachments` and `GET /emails/receiving/:id/attachments/:aid` — each attachment carries its own 1-hour signed `download_url`. These download URLs are public (no API key needed to fetch them — the signature in the query string is the authorization).
- Webhook event `email.received` fires once per team the mail was delivered for; like every event it carries metadata only (no `html`/`text`/attachment content) — call the endpoints above to fetch those.
- Sandbox: `POST /dev/inbox/receive` (only when `EMAIL_PROVIDER=log`) simulates an inbound delivery — `{ "from", "to", "cc"?, "subject"?, "html"?, "text"?, "headers"?, "attachments"? }` — without any domain needing receiving enabled or any mail actually being sent. Returns `{ "data": [{ "id" }] }`.
## API keys
- `POST /api-keys` — `{ "name", "permission"?: "full_access" | "sending_access", "domain_id"? }` (`domain_id` requires `sending_access`, else 422). Returns `{ id, object: "api_key", token }`; the token is only returned here.
- `GET /api-keys` — `{ object: "list", has_more, data: [{ id, name, created_at, last_used_at }] }`.
- `DELETE /api-keys/:id` — returns `{ object, id, deleted: true }`.
## Errors
Every error is JSON `{ "statusCode", "name", "message" }`. Branch on `name`, not on `message`.
| name | status | meaning |
| --- | --- | --- |
| missing_required_field | 422 | A required field is missing from the request body. |
| invalid_idempotency_key | 400 | The `Idempotency-Key` header is not 1–256 characters. |
| invalid_idempotent_request | 409 | The `Idempotency-Key` was reused with a different request body. Use a new key, or retry with the exact same body. |
| concurrent_idempotent_requests | 409 | Another request with the same `Idempotency-Key` is already in flight. Retry once it completes. |
| invalid_from_address | 422 | The `from` (or another address) field doesn't parse as `[email protected]` or `Name <[email protected]>`. |
| validation_error | 403 / 422 | The body failed schema validation, or the JSON itself was malformed (422), or a business rule was violated — e.g. sending from an unverified domain, re-registering a domain name, or reusing a template alias/topic name (403). |
| invalid_access | 401 / 403 | An embed or hosted-preferences token is invalid or expired (401), or a sub-account-scoped key tried to act outside its own account (403). |
| invalid_parameter | 422 | A path parameter (e.g. `:id`) isn't a valid UUID. |
| missing_api_key | 401 | No `Authorization` header was sent. |
| restricted_api_key | 401 / 403 | A `sending_access` key called a management endpoint (401), or a domain-scoped key tried to send from a non-matching domain (403). |
| invalid_api_key | 403 | The API key is malformed or does not exist. |
| account_suspended | 403 | The team, or its parent account, has been suspended. |
| domain_reputation_paused | 403 | The sending domain's bounce/complaint rate tripped the reputation circuit breaker. Call `POST /domains/:id/unpause` once it's resolved. |
| domain_blocked | 403 | The sending domain is on a spam/phishing blocklist (Spamhaus DBL, SURBL) or was blocked by us. The message names the reason. It lifts itself when the listing is removed. |
| domain_under_review | 403 | The sending domain is on hold while we review it (for example it resembles a well-known brand). Write to [email protected] if the domain is yours. |
| sending_paused | 403 | Sending is paused on the account because its bounce or complaint record crossed our safety threshold. The dashboard still works. Write to [email protected] to get it reviewed. |
| sending_held | 403 | Sending is on hold while we review the account (for example, several new accounts sent the same message). The dashboard still works. Write to [email protected]. |
| daily_quota_exceeded | 429 | The team (or sub-account) hit its daily sending quota. |
| monthly_quota_exceeded | 429 | The team (or sub-account) hit its monthly sending quota. |
| rate_limit_exceeded | 429 | Your team exceeded its requests-per-second limit. |
| not_found | 404 | The endpoint, or a resource ID owned by a different team, does not exist. |
| internal_server_error | 500 | Something went wrong on our end. Safe to retry. |
| invalid_region | — | Reserved for Resend-catalogue parity; not currently returned by any endpoint. |
| method_not_allowed | — | Reserved for Resend-catalogue parity; not currently returned by any endpoint. |
Retry only on 429 (wait `retry-after` seconds) and 5xx (exponential backoff), always with the same `Idempotency-Key`. Never retry 4xx validation/auth errors.
## Rate limits
10 requests per second per team by default, shared across all keys, fixed one-second window. Response headers: `ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`, and `retry-after` on 429. Prefer `POST /emails/batch` for bulk sends.
## Webhooks
- `POST /webhooks` — `{ "endpoint": "https://...", "events": [...] }`. Returns `{ object: "webhook", id, signing_secret }` (`whsec_...`). Store the secret as `IRISEND_WEBHOOK_SECRET`.
- `GET /webhooks`, `GET /webhooks/:id` (includes `signing_secret`), `DELETE /webhooks/:id`.
- Event types: `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`, `email.failed`, `email.scheduled`, `email.suppressed`, `email.canceled`, `email.received`, `domain.reputation.warning`, `domain.reputation.paused`, `domain.health.degraded`, `domain.health.critical`, `account.created`, `account.suspended`, `account.resumed`, `domain.dmarc.unknown_source`, `domain.dmarc.ramp_ready`. `account.*` events fire on the PARENT account's webhooks (sub-account lifecycle), not the sub-account's own.
- Payload: every delivery is a `{ "type", "created_at", "data" }` envelope, but the `data` shape depends on the event family — branch on `type` before reading `data`:
- `email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.opened, email.clicked, email.failed, email.scheduled, email.suppressed, email.canceled` → `data: { email_id, from, to, subject, created_at, tags }`
- `email.received` → `data: { email_id, created_at, from, to, bcc, cc, received_for, message_id, subject, attachments: [{ id, filename, content_type, content_disposition, content_id }] }`
- `domain.reputation.warning, domain.reputation.paused` → `data: { domain_id, domain, hard_bounce_rate, complaint_rate, sample_size, window }`
- `domain.health.degraded, domain.health.critical` → `data: { domain_id, domain, score, band, factors: [{ key, score, detail }] }`
- `account.created, account.suspended, account.resumed` → `data: { account_id, name, external_id, status, suspended_reason }`
- `domain.dmarc.unknown_source` → `data: { domain_id, domain, source_ip, messages }`
- `domain.dmarc.ramp_ready` → `data: { domain_id, domain, recommended_policy }`
- Signatures follow Standard Webhooks and are byte-compatible with Svix: headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (mirrored as `svix-*`). The `svix` and `standardwebhooks` libraries work unchanged. Verify against the raw request body exactly as received (not re-serialized JSON), reject timestamps older than 300 seconds, and respond 2xx quickly.
```js
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyIrisendWebhook(secret, headers, body) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signature = headers["webhook-signature"];
if (!id || !timestamp || !signature) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = Buffer.from(
createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64"),
);
// headers may carry several space-separated "v1,<sig>" values during rotation
return signature.split(" ").some((part) => {
const candidate = Buffer.from(part.replace(/^v1,/, ""));
return candidate.length === expected.length && timingSafeEqual(candidate, expected);
});
}
```
## Deliverability
- Hard bounces and spam complaints add the recipient to the team's suppression list automatically; suppressed recipients are dropped before sending (`email.suppressed` if none remain).
- Keep hard bounce rate under 5% and complaint rate under 0.1%.
- One-click unsubscribe (`List-Unsubscribe`) is added automatically on broadcast sends; set it yourself via `headers` on direct transactional sends if you need it there too.
## Links
- Human docs: /docs
- Migrating from Resend: /docs/migrating-from-resend
- Acceptable use policy: /legal/acceptable-useBefore you paste
- Create an API key under Configuration → API keys and keep it ready. Put it in your env file yourself — don't paste the key into the chat.
- Verify the domain you'll send from. The assistant can add it through the API, but the DNS records still have to be published at your DNS provider.
Plain-text docs for tools
The same reference, without the instructions, is served as Markdown at /llms.txt, following the llms.txt convention. Point an agent at it directly — for example, add it as a docs source in Cursor or tell Claude Code to fetch https://irisend.com/llms.txt.