# mailway

> Developer-first transactional email API. Verify a domain with 2 CNAME records,
> send via REST, get delivery events and signed webhooks. Working name; private beta.

Base URL: https://app.mailway.prevue.click/api
Auth: Authorization: Bearer mw_<key>  (create keys in the dashboard)
Spec: https://app.mailway.prevue.click/openapi.yaml (OpenAPI 3.0, source of truth)

## Core endpoints
- POST /emails — send. body: {from, to[], subject, html?, text?, cc?, bcc?, reply_to?,
  headers?, tags?, scheduled_at?}. Supports Idempotency-Key header (24h, body-hashed,
  409 on mismatch — always safe to retry).
- GET /emails/{id} — status + delivery timeline (events[]).
- POST /emails/{id}/cancel — cancel a scheduled send.
- POST/GET/DELETE /domains, POST /domains/{id}/verify — domain lifecycle.
- POST/GET/DELETE /api-keys — key management (full_access scope required).
- POST/GET/DELETE /webhooks, GET /webhooks/{id}/deliveries — signed event delivery
  (Standard Webhooks / Svix-compatible signatures).
- GET/POST/DELETE /suppressions — suppression list.

## Behavior agents should know
- Errors are typed: {name, message}. Match on `name`. Notable: domain_not_verified,
  recipient_suppressed, daily_quota_exceeded, invalid_idempotent_request.
- Statuses: queued → sent → delivered/bounced/complained; scheduled → canceled.
- Test recipients that exercise the full pipeline without real mailboxes:
  delivered@simulator.mailway.dev, bounced@…, complained@….
- Hard bounces and complaints auto-suppress the recipient; subsequent sends 403.

## Testing tips
- Simulator recipients exercise the full pipeline with no real mailbox.
- For webhook development, point an endpoint at a throwaway inspector URL from
  https://freewebhook.app to see headers, signature, and payload in real time.

## Docs
- /docs — quickstart
- /docs/domains — DNS verification (2 CNAMEs, no MX/SPF changes)
- /docs/webhooks — signature verification
- /docs/errors — error catalog