HTTP / cURL Reference

Use HTTP directly if you don't have an official SDK, or prefer working with raw HTTP requests.

Base URL

All API endpoints are under:

https://api.tratto.email/v1/

Authentication

Include your API key as a bearer token:

Authorization: Bearer tratto_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Content-Type

All requests and responses use JSON:

Content-Type: application/json

Request Format

curl -X POST https://api.tratto.email/v1/emails \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{"from":"[email protected]","to":"[email protected]","subject":"Hello","text":"World"}'

Response Format

Success (2xx):

{
  "data": { ... }
}

Error (4xx):

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Domain 'mail.acme.com' is not verified for this tenant.",
    "docs": "https://docs.tratto.email/en/domains",
    "suggestion": "Verify your domain first"
  }
}

Pagination

List endpoints support cursor-based pagination:

curl "https://api.tratto.email/v1/contacts?limit=50&after=cursor_value" \
  -H "Authorization: Bearer tratto_live_..."

Response includes:

{
  "data": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "Y3Vyc29yOnZhbHVl"
  }
}

Common Operations

Send Email

curl -X POST https://api.tratto.email/v1/emails \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Welcome!",
    "text": "Thanks for signing up"
  }'

Get Email Status

curl https://api.tratto.email/v1/emails/email_abc123 \
  -H "Authorization: Bearer tratto_live_..."

List Contacts

curl "https://api.tratto.email/v1/contacts?status=subscribed&limit=50" \
  -H "Authorization: Bearer tratto_live_..."

Create Domain

curl -X POST https://api.tratto.email/v1/domains \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain":"hello.yourdomain.com"}'

Create Campaign

curl -X POST https://api.tratto.email/v1/campaigns \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Sale",
    "templateId": "tmpl_abc123",
    "audienceId": "aud_abc123"
  }'

HTTP Headers

Header	Value	Required
`Authorization`	Bearer token	✓
`Content-Type`	`application/json`	For POST/PATCH
`Idempotency-Key`	UUID v4	For critical POST operations

cURL Tips

Pretty-print JSON

curl ... | jq '.'

Save response to file

curl ... -o response.json

Follow redirects

curl -L ...

Include headers in output

curl -i ...

Verbose output (debugging)

curl -v ...

Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request (validation error)
401	Unauthorized (invalid API key)
403	Forbidden (no permission)
404	Not Found
409	Conflict (idempotency error)
429	Too Many Requests (rate limited, or plan quota reached: check `error.code`)
500	Server Error

Next Steps

Use a compiled SDK? See Node.js SDK or Python SDK
Learn the API? Go to API Reference
Understand auth? See Authentication

HTTP / cURL Reference

On this page