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

# Introduction

> Overview of the ColdSend Public API and what you can build.

Welcome to the ColdSend Public API! This API enables developers to programmatically create and manage cold email campaigns, configure sender accounts, manage domains, and track performance.

<Info>
  The ColdSend Public API follows REST principles with JSON request/response bodies, proper HTTP status codes, and comprehensive error handling.
</Info>

## Key Capabilities

<CardGroup cols={3}>
  <Card title="Campaign Management" icon="mail">
    Create, update, pause, and launch email campaigns with full lifecycle control.
  </Card>

  <Card title="Sender Accounts" icon="inbox">
    Add and manage sender email accounts — ColdSend Native, Google Workspace, Microsoft 365, and custom SMTP.
  </Card>

  <Card title="Domain Management" icon="earth">
    Configure custom domains for professional email sending with automated DNS setup.
  </Card>

  <Card title="Lead Management" icon="users">
    Upload leads via CSV, manage lead data, and track engagement metrics.
  </Card>

  <Card title="Granular Permissions" icon="shield">
    Secure your API with scope-based access control following the principle of least privilege.
  </Card>
</CardGroup>

## What You Can Build

<AccordionGroup>
  <Accordion title="Campaign Automation Tools">
    Build tools that automatically create and launch campaigns based on triggers like form submissions, CRM updates, or scheduled events.

    <Tip>
      Use the `/api/public/v1/campaigns` endpoints to programmatically manage your entire campaign workflow.
    </Tip>
  </Accordion>

  <Accordion title="Integration Platforms">
    Connect ColdSend to your existing tech stack: CRMs, marketing automation, data processing pipelines, and custom dashboards.
  </Accordion>

  <Accordion title="Sender Account Provisioning">
    Automate onboarding by programmatically adding sender email accounts (ColdSend Native or SMTP).
  </Accordion>

  <Accordion title="Analytics and Reporting">
    Pull campaign performance data into your own analytics platforms or build custom dashboards.
  </Accordion>
</AccordionGroup>

## API Architecture

### Base URL

All API requests use the following base URL:

```text theme={null}
https://api.coldsend.pro/api/public/v1
```

### Authentication

All endpoints require authentication via API key in the `X-API-Key` header:

```text theme={null}
X-API-Key: cs_live_your_api_key_here
```

Learn more in the [Authentication Overview](/authentication/overview).

### API Versioning

The current API version is `v1`:

```text theme={null}
https://api.coldsend.pro/api/public/v1
```

### Error Handling

The API uses standard HTTP status codes:

| Status                  | Description                |
| ----------------------- | -------------------------- |
| `200 OK`                | Request succeeded          |
| `201 Created`           | Resource created           |
| `204 No Content`        | Succeeded with no body     |
| `400 Bad Request`       | Invalid request            |
| `401 Unauthorized`      | Missing or invalid API key |
| `403 Forbidden`         | Insufficient scopes        |
| `404 Not Found`         | Resource doesn't exist     |
| `409 Conflict`          | Resource already exists    |
| `422 Unprocessable`     | Validation error           |
| `429 Too Many Requests` | Rate limit exceeded        |

## Key Concepts

<AccordionGroup>
  <Accordion title="Campaign Lifecycle">
    Campaigns progress through: `DRAFT` → `ACTIVE` → `PAUSED` → `COMPLETED` or `FAILED`.

    <Tip>
      Create campaigns in DRAFT, configure all components, then set `launch: true` to activate.
    </Tip>
  </Accordion>

  <Accordion title="Scope-Based Security">
    API keys use granular scopes. Follow the principle of least privilege — grant only the scopes your integration needs.

    Learn more in [API Key Scopes](/authentication/scopes).
  </Accordion>

  <Accordion title="ColdSend Native vs SMTP">
    Choose ColdSend Native for managed infrastructure (no SMTP config needed) or SMTP/BYOC for your own email accounts with custom credentials.

    Learn more in [Sender Accounts Overview](/sender-accounts/overview).
  </Accordion>

  <Accordion title="Email Variants and A/B Testing">
    Up to 4 variants per campaign. Leads are randomly assigned by distribution percentage.

    Learn more in [Email Variants](/campaigns/variants).
  </Accordion>

  <Accordion title="Follow-up Sequences">
    Up to 3 follow-up steps with triggers like `NOT_OPENED`, `NOT_REPLIED`, and `OPENED_BUT_NOT_REPLIED`.

    Learn more in [Follow-up Sequences](/campaigns/sequences).
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup cols={3}>
  <Card title="Quickstart" icon="zap" href="/getting-started/quickstart">
    Get your first campaign up and running.
  </Card>

  <Card title="Reference" icon="book-open" href="/reference/errors">
    Error codes, rate limits, and API reference.
  </Card>

  <Card title="Authentication" icon="shield" href="/authentication/overview">
    API keys, scopes, and security.
  </Card>

  <Card title="Campaigns" icon="mail" href="/campaigns/overview">
    Campaign creation, lifecycle, and management.
  </Card>

  <Card title="Sender Accounts" icon="inbox" href="/sender-accounts/overview">
    Configure sender email accounts.
  </Card>
</CardGroup>