Documentation / API Reference

API Overview

4 min read

The MailingAPI REST API lets you send transactional emails, manage domains, configure webhooks, and access analytics programmatically.

Base URL

All API requests use this base URL:

https://api.mailingapi.com/v1

Authentication

Authenticate using Bearer tokens in the Authorization header:

curl https://api.mailingapi.com/v1/messages \
  -H "Authorization: Bearer your_api_key_here"

API keys are scoped to a single domain. Get your key from Settings → API Keys.

See Authentication for details.

Request format

Content-Type

Send JSON with Content-Type: application/json:

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "hello@yourdomain.com", "to": "user@example.com", ...}'

Request body

All POST/PUT/PATCH requests accept JSON bodies:

{
  "from": "hello@yourdomain.com",
  "to": "user@example.com",
  "subject": "Hello",
  "html": "<p>Hello world</p>"
}

Response format

All responses return JSON with consistent structure.

Success response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "from": "hello@yourdomain.com",
    "to": "user@example.com",
    "subject": "Hello",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

List response

{
  "data": [
    {"id": "550e8400-...", "status": "delivered"}
  ],
  "meta": {
    "count": 25,
    "total": 150,
    "limit": 25,
    "offset": 0,
    "has_more": true
  }
}

Error response

{
  "error": {
    "message": "Invalid email address format"
  }
}

HTTP methods

Method Usage
GET Retrieve resources
POST Create resources
PATCH Partial update
PUT Full replacement
DELETE Remove resources

Status codes

Code Meaning
200 Success
201 Created
204 No content (successful delete)
400 Bad request (invalid input)
401 Unauthorized (invalid/missing API key)
403 Forbidden (insufficient permissions)
404 Not found
422 Unprocessable entity (validation failed)
429 Too many requests (rate limited)
500 Internal server error

Pagination

List endpoints support pagination:

curl "https://api.mailingapi.com/v1/messages?limit=50&offset=0" \
  -H "Authorization: Bearer $API_KEY"

Parameters:

  • limit — Items per page (default: 50, max: 100)
  • offset — Number of results to skip (default: 0)

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "count": 50,
    "total": 150,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

Filtering

Many endpoints support filtering:

curl "https://api.mailingapi.com/v1/messages?status=delivered&from=2024-01-01" \
  -H "Authorization: Bearer $API_KEY"

Common filters:

  • since / until — Date range (ISO 8601)
  • status — Resource status
  • to — Filter by recipient

Rate limiting

API requests are rate limited per API key:

Endpoint Limit
Send email 100/minute, 10/second burst
Read endpoints 1000/minute
Management endpoints 100/minute

Successful responses include these headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705315860

X-RateLimit-Reset is a Unix timestamp in seconds. If the domain has a daily send limit, responses also include X-Daily-Limit and X-Daily-Remaining.

When rate limited, you receive 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "retry_after": 5
  }
}

Every 429 always includes the standard Retry-After header (integer seconds) and the same value as retry_after in the body. We recommend reading the Retry-After header. A per-second or per-minute 429 also carries the X-RateLimit-* headers; a daily-limit 429 (daily_limit_exceeded) carries X-Daily-Limit and X-Daily-Remaining: 0. A 429 with recipient_rate_limited means the same recipient received too many emails from your organization (max 10 per hour, 50 per day). See Error Handling for all error codes.

API reference and OpenAPI

The interactive API reference (Swagger UI) is at /api/docs and requires JavaScript. The machine-readable OpenAPI 3 specification (JSON) is at /api/openapi.

Idempotency

POST /v1/messages/send, POST /v1/messages/batch and POST /v1/messages/analyze accept an Idempotency-Key header. Send the same key when retrying a request, so a timeout or network error never results in a duplicate email:

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9c2a8e-6b1d-4c3e-9a7f-2d5e8b1c0a93" \
  -d '{...}'
  • The key is 1–255 characters. Use a UUID or another identifier that is unique per logical request (for example your order ID).
  • Keys are scoped to the API key and are valid for 24 hours.
  • The header is optional. Without it, every request is processed independently.
  • A batch is one unit: retrying /v1/messages/batch with the same key replays the whole batch response — no message from it is sent twice.
Situation Response Retry?
First request with the key Processed normally; the response is stored —
Same key, same body The original status and body, with header Idempotent-Replayed: true. Nothing is sent again —
Same key, different body 422 idempotency_key_reused No — use a new key
Same key while the first request is still processing 409 idempotency_request_in_progress, Retry-After: 1 Yes, after Retry-After seconds
Invalid key (empty or longer than 255 characters) 400 invalid_idempotency_key No

Both success and client-error responses (2xx, 4xx) are stored and replayed. Server errors (5xx) and 429 are not stored, so a retry with the same key runs the request again.

The body is compared by content, not by formatting — reordering JSON fields does not count as a different body.

Versioning

The API is versioned via URL path:

https://api.mailingapi.com/v1/...

We maintain backwards compatibility within major versions. Breaking changes require a new version.

SDKs

Official SDKs available:

See the full SDK documentation for installation guides and examples.

API resources

Resource Description
Messages Send and track emails
Domains Manage sending domains
Webhooks Configure event notifications
Templates Email templates
Validation Email address validation