Skip to main content

API Overview

The Sendmator API provides everything you need for contact management and email sending. It's designed around REST principles with JSON-encoded requests and responses.

Core Features​

  • 📧 Universal Email Sending - Send to individual contacts, tags, or all contacts with one endpoint
  • 👥 Contact Management - Full CRUD operations with custom fields and external ID support
  • 🎯 Smart Targeting - Organize contacts with tags for precise audience segmentation
  • 🔄 Auto-Variables - Contact data automatically available as template variables
  • 📊 Built-in Tracking - Email opens, clicks, replies, and delivery status
  • ⚡ Async Processing - Large sends processed in background for optimal performance

For template management, campaign analytics, and advanced features, use the Sendmator web dashboard.

Base URL​

All API requests should be made to:

https://api.sendmator.com/v1

Authentication​

Include your API key in the X-API-Key header:

X-API-Key: your-api-key

Request Format​

All requests should include the Content-Type header:

Content-Type: application/json

Example request:

curl -X POST https://api.sendmator.com/v1/messages/send-async \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"recipient_type": "contact", "contact_external_id": "user_123", "subject": "Welcome!", "content": "Welcome {{contact_first_name}}!"}'

Response Format​

All responses are JSON objects with consistent structure:

Success Response​

{
  "execution_id": "exec_abc123def456",
  "status": "queued", 
  "recipient_type": "contact",
  "estimated_recipients": 1,
  "created_at": "2024-01-15T10:30:00Z"
}

Error Response​

{
  "error": {
    "type": "validation_error",
    "message": "Missing required field: to",
    "details": {
      "field": "to",
      "code": "required"
    }
  }
}

HTTP Status Codes​

CodeDescription
200OK - Request succeeded
201Created - Resource created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - Resource not found
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong

Rate Limits​

API requests are rate limited based on your plan:

PlanRequests per Hour
Free100
Pro10,000
EnterpriseCustom

Rate limit information is included in response headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9999
X-RateLimit-Reset: 1640995200

Pagination​

List endpoints support cursor-based pagination:

curl -H "X-API-Key: sk_live_your_api_key" \
     "https://api.sendmator.com/v1/contacts?limit=10&starting_after=contact_abc123"

Response includes pagination metadata:

{
  "data": [...],
  "has_more": true,
  "next_cursor": "msg_def456"
}

Idempotency​

For safe retries, include an Idempotency-Key header:

curl -X POST https://api.sendmator.com/v1/messages/send-async \
  -H "Idempotency-Key: unique-key-123" \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"recipient_type": "contact", "contact_external_id": "user_123"}'

Timestamps​

All timestamps are returned in ISO 8601 format (UTC):

{
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:35:00Z"
}

Webhooks​

Sendmator can send webhooks to notify your application of events:

{
  "id": "evt_abc123",
  "type": "message.delivered",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "execution_id": "exec_abc123def456",
    "message_id": "msg_abc123",
    "status": "delivered"
  }
}

Available Endpoints​

Contacts​

Email Sending​

Language Examples​

While we don't have official SDKs yet, you can easily integrate with any language that supports HTTP requests. Here are examples in popular languages:

Need Help?​