API Overview

Get started with the Mailnaptic REST API

API Overview

The Mailnaptic REST API gives you programmatic access to your email marketing platform. You can manage contacts, send emails, create campaigns, build segments, and retrieve analytics data — all through standard HTTP requests.

Base URL

All API requests are made to your Mailnaptic instance's base URL:

https://your-mailnaptic-domain/api/v1

All requests must use HTTPS. HTTP requests are rejected.

Authentication

Authenticate API requests using an API key passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are created in Organization → API Keys. Each key has scoped permissions that control which resources it can read or write. See Creating API Keys and API Key Scopes for details.

Request format

For endpoints that accept a request body (POST, PUT, PATCH), send JSON with the Content-Type: application/json header:

curl -X POST https://your-mailnaptic-domain/api/v1/contacts 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"email": "jane@example.com", "first_name": "Jane"}'

Response format

All responses return JSON. Successful responses include the requested data:

{
  "success": true,
  "data": {
    "id": 12345,
    "email": "jane@example.com",
    "first_name": "Jane"
  }
}

Error responses include a human-readable message:

{
  "success": false,
  "error": "Contact not found",
  "code": "NOT_FOUND"
}

HTTP status codes

Rate limiting

API requests are rate-limited per API key. The default limits are:

• General endpoints: 100 requests per minute
• Transactional email: 300 requests per minute
• Bulk operations: 10 requests per minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1679145600

When rate limited, you receive a 429 response. Wait until the X-RateLimit-Reset timestamp before retrying.

Pagination

List endpoints return paginated results. Use page and per_page query parameters:

GET /api/v1/contacts?page=2&per_page=50

The response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "per_page": 50,
    "total": 1234,
    "total_pages": 25
  }
}

Available resources

• Contacts — create, read, update, delete contacts and manage tags
• Lists — manage subscription lists
• Segments — create and query dynamic segments
• Campaigns — create, schedule, and send campaigns
• Transactional emails — send one-off emails via the API
• Domains — manage sending domains and DNS records
• Organization — manage settings and API keys

Tip: Use the test.ping endpoint (GET /api/v1/ping) to verify your API key and connectivity before building your integration.