Skip to main content

API Overview

The Sendmator API provides everything you need for contact management and multi-channel message sending (email, SMS, WhatsApp and push). It's designed around REST principles with JSON-encoded requests and responses.

Core Features​

  • 📧 Multi-Channel Messaging - Send email, SMS, WhatsApp, and push notifications from one unified API
  • 👥 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 - Delivery status, opens, clicks, and engagement analytics across all channels
  • ⚡ 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/api/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/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"recipient_type": "contact", "contact_external_id": "user_123", "template_key": "welcome-email", "variables": {"name": "John"}}'

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/api/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/api/v1/messages/send \
  -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", "template_key": "welcome-email"}'

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​

Multi-Channel Messaging​

Email​

SMS​

WhatsApp​

Push Notifications​

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?​