Documentation / API Reference

API Overview

2 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

Rate limit headers are included in responses:

x-ratelimit-limit: 100
x-ratelimit-remaining: 95
x-ratelimit-reset: 1705315860

When rate limited, you receive 429 Too Many Requests:

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

Idempotency

For POST requests, use idempotency keys to prevent duplicates:

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{...}'
  • Keys are valid for 24 hours
  • Repeated requests with same key return original response
  • Use UUIDs or unique identifiers

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