# API Overview

Get started with the Mailnaptic REST API

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

| Code | Meaning |
| --- | --- |
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request (invalid parameters) |
| `401` | Unauthorized (missing or invalid API key) |
| `403` | Forbidden (API key lacks required scope) |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Internal server error |

## 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.
