> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendykit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> SendyKit REST API v2 — 125 endpoints for complete email marketing automation

## Base URL

```
https://your-server.com/sendykit/api/v2
```

For SaaS: `https://api.sendykit.dev/v2`

## Authentication

All API requests require authentication via one of:

### API Key (recommended for integrations)

```bash theme={null}
curl -H "X-API-Key: sk_a1b2c3d4..." \
  https://your-server.com/sendykit/api/v2/brands
```

API keys are SHA-256 hashed at rest, scoped (`read`, `write`, `admin`), and individually revocable.

### JWT Token (for sessions)

```bash theme={null}
# Get a token
curl -X POST https://your-server.com/sendykit/api/v2/auth/token \
  -d '{"username": "admin", "password": "..."}'

# Use it
curl -H "Authorization: Bearer eyJ..." \
  https://your-server.com/sendykit/api/v2/brands
```

### Machine Payments (for agents)

For premium actions, SendyKit can require Stripe-native machine-payment proof:

```bash theme={null}
curl -H "X-Stripe-Machine-Payment: <payment-proof-or-intent-ref>" \
  https://your-server.com/sendykit/api/v2/campaigns
```

Use API keys for standard authenticated automation. Use Stripe-native machine-payment proofs for premium machine-paid actions.

## Response Format

All responses use a consistent JSON envelope:

```json theme={null}
{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 142
  }
}
```

Error responses:

```json theme={null}
{
  "error": "subscriber not found",
  "code": "not_found",
  "status": 404
}
```

## Idempotency

For write operations (POST, PUT, DELETE), include an `Idempotency-Key` header to prevent duplicate processing:

```bash theme={null}
curl -X POST \
  -H "X-API-Key: sk_..." \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"email": "user@example.com", "list_id": 1}' \
  https://your-server.com/sendykit/api/v2/subscribers
```

## Rate Limiting

Rate limits are returned in response headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1710345600
```

Default limits per API key. Contact support for higher limits.

## Endpoint Categories

SendyKit’s generated API reference covers the major families below. Use the **API Reference** tab navigation and OpenAPI-powered endpoint pages for the full route surface.

| Category    | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| Brands      | Multi-brand management                                          |
| Lists       | Mailing list CRUD + custom fields                               |
| Subscribers | Full subscriber lifecycle + bulk operations                     |
| Campaigns   | Campaign CRUD, scheduling, sending, and reports                 |
| Templates   | Template management                                             |
| Analytics   | Delivery, engagement, and campaign intelligence                 |
| AI          | Subject lines, email generation, rewrites, and insights         |
| Webhooks    | Event subscriptions and delivery operations                     |
| System      | Health, doctor, audit, flags, and operational endpoints         |
| Billing     | Status, customer state, licensing, and machine-payment receipts |

<Note>
  The endpoint pages in the API Reference tab are generated from the canonical OpenAPI spec, so they stay aligned with the live contract more reliably than hand-maintained deep links.
</Note>