Developer guideGetting started
Developer guide
Everything you need to send transactional email with Couryo, over the REST API or from your AI agent (MCP).
Couryo is a transactional and product email API. You send over the REST API (https://api.couryo.com/v1) or from your AI agent with the MCP server (https://mcp.couryo.com), follow every message on a timeline that includes the receiving server's original response, and get events by webhook. SMTP is coming soon.
Where to start#
- Quickstart: your first email in 5 minutes.
- Authentication and keys:
ck_live_andck_test_keys, scopes and allowed IPs. - Sending email: idempotency, batch, scheduling, tags and attachments.
- Domains and DNS: what each record does and how to verify.
- Webhooks: events signed with Standard Webhooks.
- Errors: every code, with cause and fix.
API principles#
- REST and JSON, dates in ISO 8601 UTC (
2026-10-07T18:30:00Z). - Prefixed, random IDs:
msg_(email),dom_(domain),key_(key),whk_(webhook),evt_(event), always 16 characters after the prefix. - No fake success. A
202only comes back once the email is in the queue. If something prevents sending, you get an error with a stable code and an explanation. - Idempotency on every POST, with the
Idempotency-Keyheader. - Cursor pagination:
?limit=25&starting_after=<id>returns{ "data": [...], "has_more": true }. - Messages in English or Portuguese, following the
Accept-Languageheader (the default ispt-BR; sendAccept-Language: enfor English).
Endpoints#
| Method and path | What it does |
|---|---|
POST /v1/emails |
sends an email |
POST /v1/emails/batch |
sends up to 100 emails in one request |
GET /v1/emails and GET /v1/emails/{id} |
lists emails or returns one, with its timeline |
POST /v1/emails/check |
checks an email before sending, without sending it |
GET and POST /v1/domains |
lists and creates domains |
GET and DELETE /v1/domains/{id}, POST /v1/domains/{id}/verify |
reads, deletes and verifies a domain |
GET and POST /v1/webhooks, GET, PATCH and DELETE /v1/webhooks/{id} |
webhooks |
GET and POST /v1/suppressions, DELETE /v1/suppressions/{email} |
suppression list |
GET /v1/events |
events, for when you missed a webhook |
GET /openapi.json |
the API's OpenAPI 3.1 spec, no key needed |
For AI agents#
This whole guide is available as Markdown. Add .md to any URL (for example, /en/docs/quickstart.md) or use llms.txt and llms-full.txt. Pricing is at /pricing.md.