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

# API Reference

> Complete API reference for Sequenzy

# API Reference

The Sequenzy API lets you programmatically manage subscribers, send emails, trigger events, and integrate email marketing into your application.

## Base URL

All API requests are made to:

```
https://api.sequenzy.com/api/v1
```

For backwards compatibility, requests to `https://api.sequenzy.com/v1` are still accepted as an alias.

## Authentication

All endpoints require an API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Get your API key from [the Sequenzy dashboard](https://www.sequenzy.com/dashboard). After you sign in, go to **Settings → API Keys**.

<Card title="Authentication Guide" icon="key" href="/authentication">
  Learn more about API authentication
</Card>

For agentic API or MCP access, use the user-approved flow in [auth.md](https://www.sequenzy.com/auth.md). This is separate from normal dashboard account signup. Agents that need dashboard-session setup notes can read [agents.md](https://www.sequenzy.com/agents.md).

## Response Format

All responses return JSON with a consistent structure.

### Success Response

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": "Human readable error message"
}
```

## HTTP Status Codes

| Status | Description                                                       |
| ------ | ----------------------------------------------------------------- |
| `200`  | Success                                                           |
| `400`  | Bad request (validation error, missing fields, disabled resource) |
| `401`  | Unauthorized (invalid or missing API key)                         |
| `404`  | Resource not found                                                |
| `409`  | Conflict (resource already exists)                                |
| `500`  | Internal server error                                             |

## Available Endpoints

### Subscribers

Manage your subscriber list.

| Method   | Endpoint                    | Description            |
| -------- | --------------------------- | ---------------------- |
| `POST`   | `/subscribers`              | Create subscriber      |
| `GET`    | `/subscribers`              | List subscribers       |
| `GET`    | `/subscribers/:email`       | Get subscriber         |
| `PATCH`  | `/subscribers/:email`       | Update subscriber      |
| `DELETE` | `/subscribers/:email`       | Delete subscriber      |
| `GET`    | `/subscribers/:email/notes` | List subscriber notes  |
| `POST`   | `/subscribers/:email/notes` | Create subscriber note |

### Tags

Segment subscribers with tags.

| Method | Endpoint                 | Description           |
| ------ | ------------------------ | --------------------- |
| `POST` | `/subscribers/tags`      | Add tag to subscriber |
| `POST` | `/subscribers/tags/bulk` | Add multiple tags     |

### Events

Track subscriber actions and trigger automations.

| Method | Endpoint                   | Description             |
| ------ | -------------------------- | ----------------------- |
| `POST` | `/subscribers/events`      | Trigger event           |
| `POST` | `/subscribers/events/bulk` | Trigger multiple events |

### Sequences

Create and manage automation sequences.

| Method   | Endpoint                         | Description      |
| -------- | -------------------------------- | ---------------- |
| `GET`    | `/sequences`                     | List sequences   |
| `POST`   | `/sequences`                     | Create sequence  |
| `GET`    | `/sequences/:sequenceId`         | Get sequence     |
| `PUT`    | `/sequences/:sequenceId`         | Update sequence  |
| `POST`   | `/sequences/:sequenceId/enable`  | Enable sequence  |
| `POST`   | `/sequences/:sequenceId/disable` | Disable sequence |
| `DELETE` | `/sequences/:sequenceId`         | Delete sequence  |

### Generation

Generate draft email content for review.

| Method | Endpoint             | Description                                             |
| ------ | -------------------- | ------------------------------------------------------- |
| `POST` | `/generate/email`    | Generate a draft email                                  |
| `POST` | `/generate/sequence` | Deprecated alias that creates a disabled sequence draft |
| `POST` | `/generate/subjects` | Generate subject line ideas                             |

### Transactional Emails

Send programmatic emails.

| Method | Endpoint               | Description          |
| ------ | ---------------------- | -------------------- |
| `POST` | `/transactional/send`  | Send email           |
| `GET`  | `/transactional`       | List templates       |
| `GET`  | `/transactional/:slug` | Get template details |

## Auto-Creation Behavior

The API automatically creates resources when they don't exist:

| Resource        | When Created                                                                        |
| --------------- | ----------------------------------------------------------------------------------- |
| **Subscribers** | When adding tags, triggering events, or sending transactional emails to a new email |
| **Tags**        | When adding a tag that doesn't exist                                                |
| **Events**      | When triggering an event type that doesn't exist                                    |

This makes integration seamless—you don't need to pre-configure anything in the dashboard.

### Example

```bash theme={null}
# This single request will:
# 1. Create the subscriber (if new)
# 2. Create the "customer" tag (if new)
# 3. Add the tag to the subscriber

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new-user@example.com",
    "tag": "customer"
  }'
```

## Rate Limiting

The API is rate limited to protect service stability:

* **Standard limit**: 100 requests per minute per API key
* **Burst limit**: 20 requests per second

When rate limited, you'll receive a `429 Too Many Requests` response with a `Retry-After` header.

## Pagination

List endpoints support pagination:

| Parameter | Type    | Default | Description              |
| --------- | ------- | ------- | ------------------------ |
| `page`    | integer | 1       | Page number              |
| `limit`   | integer | 20      | Items per page (max 100) |

### Example

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/subscribers?page=2&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json theme={null}
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 1250,
    "totalPages": 25
  }
}
```

## Error Handling

### Common Error Codes

| Error                  | Description                | Solution                    |
| ---------------------- | -------------------------- | --------------------------- |
| `Unauthorized`         | Invalid or missing API key | Check your API key          |
| `Subscriber not found` | Email doesn't exist        | Create the subscriber first |
| `Template not found`   | Invalid template slug      | Check the slug spelling     |
| `Template disabled`    | Template is deactivated    | Enable in dashboard         |
| `Validation error`     | Missing or invalid fields  | Check request body          |

### Example Error Response

```json theme={null}
{
  "success": false,
  "error": "Subscriber not found"
}
```

## SDK & Libraries

### Node.js / TypeScript SDK (Recommended)

Install the official Sequenzy SDK for the best developer experience:

```bash theme={null}
npm install sequenzy
# or
pnpm add sequenzy
# or
bun add sequenzy
```

```typescript theme={null}
import Sequenzy from "sequenzy";

const client = new Sequenzy({
  apiKey: process.env.SEQUENZY_API_KEY,
});

// Create a subscriber
await client.subscribers.create({
  email: "user@example.com",
  firstName: "John",
  tags: ["new-signup"],
  customAttributes: { plan: "pro" },
  enrollInSequences: true,
});

// Add a tag
await client.subscribers.tags.add({
  email: "user@example.com",
  tag: "customer",
});

// Trigger an event
await client.subscribers.events.trigger({
  email: "user@example.com",
  event: "purchase_completed",
  properties: { orderId: "ORD-123", amount: 99.99 },
});

// Send a transactional email
await client.transactional.send({
  to: "user@example.com",
  slug: "welcome-email",
  variables: { firstName: "John" },
});
```

### TypeScript/JavaScript (Fetch API)

If you prefer to use the REST API directly:

```javascript theme={null}
async function addTag(email, tag) {
  const response = await fetch(
    "https://api.sequenzy.com/api/v1/subscribers/tags",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.SEQUENZY_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email, tag }),
    }
  );
  return response.json();
}
```

### Python

```python theme={null}
import requests

def add_tag(email, tag):
    response = requests.post(
        "https://api.sequenzy.com/api/v1/subscribers/tags",
        headers={
            "Authorization": f"Bearer {SEQUENZY_API_KEY}",
            "Content-Type": "application/json"
        },
        json={"email": email, "tag": tag}
    )
    return response.json()
```

### cURL

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "tag": "customer"}'
```

## Need Help?

* **Email**: [nic@sequenzy.com](mailto:nic@sequenzy.com)
* **Twitter**: [@nikpolale](https://x.com/nikpolale)