# 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 <hello@yourdomain.com>",
    "to": ["you@example.com"],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>",
    "text": "Thanks for your order."
  }'
```

Response: `{ "id": "em_9f2K3mQ1zPr7vT6yB4wL0nC" }`

Body fields:
- `from` (required): `email@example.com` or `Name <email@example.com>`, 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@example.com` or `Name <email@example.com>`. |
| 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 support@irisend.com 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 support@irisend.com 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 support@irisend.com. |
| 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-use
