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

# Introduction

> Get started with the FoxReach API to manage leads, campaigns, email accounts, templates, and webhooks programmatically.

## Welcome to the FoxReach API

The FoxReach API lets you integrate your cold email outreach platform with your existing tools, CRMs, and automation workflows. Build powerful integrations to manage your leads, campaigns, and email infrastructure programmatically.

### What you can do

<CardGroup cols={2}>
  <Card title="Manage Leads" icon="users" href="/docs/api-reference/leads/list-leads">
    Create, update, and organize your leads. Import contacts from your CRM or sync them in real-time.
  </Card>

  <Card title="Control Campaigns" icon="paper-plane" href="/docs/api-reference/campaigns/list-campaigns">
    Create multi-step email campaigns, start and pause them, and monitor performance.
  </Card>

  <Card title="Email Accounts" icon="envelope" href="/docs/api-reference/email-accounts/list-accounts">
    View your connected email accounts, warmup settings, and health metrics.
  </Card>

  <Card title="Templates & Variables" icon="file-lines" href="/docs/template-variables">
    Build reusable email templates with personalization variables and spin syntax for deliverability.
  </Card>

  <Card title="MCP Server" icon="robot" href="/docs/mcp-server">
    Connect AI agents like Claude and Cursor to FoxReach. Manage leads and campaigns through natural language.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/docs/webhooks/overview">
    Receive real-time notifications when emails are sent, replies come in, or campaigns complete.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/docs/errors">
    Understand error codes and build resilient integrations with proper error handling.
  </Card>
</CardGroup>

## Quick Start

### Prerequisites

* A FoxReach account with an active workspace
* An API key (create one in **Settings > API Keys**)

### Make your first request

<Steps>
  <Step title="Get your API key">
    Go to **Settings > API Keys** in the [dashboard](https://www.foxreach.io/settings?tab=api-keys) and create a new key. Copy it — you'll only see it once.
  </Step>

  <Step title="List your leads">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X GET https://api.foxreach.io/api/v1/leads \
        -H "X-API-Key: otr_your_api_key_here"
      ```

      ```python Python theme={null}
      import requests

      response = requests.get(
          "https://api.foxreach.io/api/v1/leads",
          headers={"X-API-Key": "otr_your_api_key_here"}
      )
      leads = response.json()
      ```

      ```javascript Node.js theme={null}
      const response = await fetch(
        "https://api.foxreach.io/api/v1/leads",
        { headers: { "X-API-Key": "otr_your_api_key_here" } }
      );
      const leads = await response.json();
      ```
    </CodeGroup>
  </Step>

  <Step title="Check the response">
    ```json theme={null}
    {
      "data": [
        {
          "id": "cld_abc123",
          "email": "john@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "company": "Acme Inc",
          "status": "active",
          "createdAt": "2025-01-15T10:30:00"
        }
      ],
      "meta": {
        "page": 1,
        "pageSize": 50,
        "total": 1,
        "totalPages": 1
      }
    }
    ```
  </Step>
</Steps>

## Base URL

All API requests are made to:

```
https://api.foxreach.io/api/v1
```

## Authentication

Include your API key in the `X-API-Key` header with every request. See [Authentication](/docs/authentication) for details.

```bash theme={null}
-H "X-API-Key: otr_your_api_key_here"
```

## Response Format

All responses use a consistent envelope format.

**Single resource:**

```json theme={null}
{
  "data": { ... }
}
```

**List of resources:**

```json theme={null}
{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "total": 100,
    "totalPages": 2
  }
}
```

**Error:**

```json theme={null}
{
  "detail": "Lead not found"
}
```

See [Errors](/docs/errors) for a full reference of error codes and formats.

## HTTP Status Codes

| Code  | Description                           |
| ----- | ------------------------------------- |
| `200` | Request succeeded                     |
| `201` | Resource created successfully         |
| `204` | Resource deleted successfully         |
| `400` | Bad request — check your request body |
| `403` | Invalid or missing API key            |
| `404` | Resource not found                    |
| `409` | Conflict — resource already exists    |
| `422` | Validation error — check field values |
| `429` | Rate limit exceeded — slow down       |
| `500` | Server error — retry with backoff     |

## Need Help?

If you run into issues or have questions, reach out to our support team from the [dashboard](https://www.foxreach.io).