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

# Sender Accounts Overview

> Connect and manage email accounts for sending campaigns.

Sender accounts are email addresses used to send your ColdSend campaigns. ColdSend supports two main infrastructure types: **ColdSend Native** (managed) and **SMTP/BYOC** (bring your own credentials).

<Info>
  Unlike the old single-endpoint model, sender accounts are now created via type-specific endpoints: `POST /sender-accounts/coldsend-native` for managed accounts and `POST /sender-accounts/smtp` for SMTP accounts.
</Info>

## Account Types

### ColdSend Native

Managed email infrastructure provided by ColdSend for optimal deliverability and simplified setup.

| Feature                         | Description                                                  |
| ------------------------------- | ------------------------------------------------------------ |
| **Automatic Setup**             | No SMTP/IMAP configuration needed                            |
| **Deliverability Optimization** | ColdSend manages domain reputation                           |
| **Bounce Handling**             | Automatic bounce processing via Azure Communication Services |
| **Reply Tracking**              | Native integration via Mailcow                               |

**Endpoint:** `POST /api/public/v1/sender-accounts/coldsend-native`

```python theme={null}
import requests

response = requests.post(
    "https://api.coldsend.pro/api/public/v1/sender-accounts/coldsend-native",
    headers={"X-API-Key": api_key},
    json={
        "domain_id": "550e8400-e29b-41d4-a716-446655440000",
        "email_prefix": "john",
        "display_name": "John Smith from Company"
    }
)
```

<Tip>
  ColdSend Native inboxes are created on domains already managed by your ColdSend workspace. You specify a `domain_id` and an email prefix (e.g., `john` → `john@yourdomain.com`).
</Tip>

Bulk creation is also supported via `POST /api/public/v1/sender-accounts/coldsend-native/bulk`:

```python theme={null}
response = requests.post(
    "https://api.coldsend.pro/api/public/v1/sender-accounts/coldsend-native/bulk",
    headers={"X-API-Key": api_key},
    json={
        "domain_id": "550e8400-e29b-41d4-a716-446655440000",
        "inboxes": [
            {"email_prefix": "john", "display_name": "John Smith"},
            {"email_prefix": "sales", "display_name": "Sales Team"}
        ]
    }
)
```

### SMTP / BYOC (Bring Your Own Credentials)

Use your existing email accounts with custom SMTP/IMAP settings. Supported provider types: `GOOGLE_WORKSPACE`, `OUTLOOK_365`, and `CUSTOM_SMTP`.

**Endpoint:** `POST /api/public/v1/sender-accounts/smtp`

```python theme={null}
response = requests.post(
    "https://api.coldsend.pro/api/public/v1/sender-accounts/smtp",
    headers={"X-API-Key": api_key},
    json={
        "email_address": "outreach@company.com",
        "display_name": "John Smith from Company",
        "inbox_type": "GOOGLE_WORKSPACE",
        "daily_limit": 50,
        "smtp_host": "smtp.gmail.com",
        "smtp_port": 587,
        "smtp_username": "outreach@company.com",
        "smtp_password": "your-app-password",
        "smtp_use_tls": True,
        "imap_host": "imap.gmail.com",
        "imap_port": 993,
        "imap_username": "outreach@company.com",
        "imap_password": "your-app-password",
        "imap_use_ssl": True
    }
)
```

<Warning>
  Use app-specific passwords, not your main account password. For Gmail, generate one at Google Account → Security → App Passwords.
</Warning>

Provider max daily limits:

| Provider           | Max Daily Limit |
| ------------------ | --------------- |
| `GOOGLE_WORKSPACE` | 2,000           |
| `OUTLOOK_365`      | 5,000           |
| `CUSTOM_SMTP`      | 100,000         |

Bulk SMTP creation is supported via `POST /api/public/v1/sender-accounts/smtp/bulk`. Each inbox's SMTP/IMAP connections are tested asynchronously. The response includes a `job_id` you can poll at `GET /api/public/v1/sender-accounts/smtp/bulk/{job_id}/progress`.

```python theme={null}
response = requests.post(
    "https://api.coldsend.pro/api/public/v1/sender-accounts/smtp/bulk",
    headers={"X-API-Key": api_key},
    json={
        "inboxes": [
            {
                "email_address": "outreach@company.com",
                "display_name": "Outreach Team",
                "inbox_type": "GOOGLE_WORKSPACE",
                "daily_limit": 50,
                "smtp_host": "smtp.gmail.com",
                "smtp_port": 587,
                "smtp_username": "outreach@company.com",
                "smtp_password": "your-app-password",
                "smtp_use_tls": True,
                "imap_host": "imap.gmail.com",
                "imap_port": 993,
                "imap_username": "outreach@company.com",
                "imap_password": "your-app-password",
                "imap_use_ssl": True
            }
        ]
    }
)
job_id = response.json()["job_id"]

# Poll for progress
import time
while True:
    progress = requests.get(
        f"https://api.coldsend.pro/api/public/v1/sender-accounts/smtp/bulk/{job_id}/progress",
        headers={"X-API-Key": api_key}
    ).json()
    if progress["status"] in ("COMPLETED", "FAILED"):
        break
    time.sleep(3)
```

## Bulk Delete Sender Accounts

**POST** `/api/public/v1/sender-accounts/bulk/delete`

Delete up to 100 sender accounts in a single async job. The request returns immediately with a `job_id`; poll the progress endpoint to track completion.

```python theme={null}
response = requests.post(
    "https://api.coldsend.pro/api/public/v1/sender-accounts/bulk/delete",
    headers={"X-API-Key": api_key},
    json={
        "inbox_ids": [
            "750e8400-e29b-41d4-a716-446655440000",
            "850e8400-e29b-41d4-a716-446655440001"
        ]
    }
)
job_id = response.json()["job_id"]
```

**GET** `/api/public/v1/sender-accounts/bulk/delete/{job_id}/progress`

Poll this endpoint to track bulk delete progress:

```python theme={null}
progress = requests.get(
    f"https://api.coldsend.pro/api/public/v1/sender-accounts/bulk/delete/{job_id}/progress",
    headers={"X-API-Key": api_key}
).json()
print(progress["status"], progress["completed"], "/", progress["total"])
```

<Warning>
  Deleting a sender account removes it from all campaigns it was assigned to. Accounts actively sending emails in a running campaign should be removed from that campaign first.
</Warning>

## API Endpoints

| Method     | Endpoint                                         | Description                                      |
| ---------- | ------------------------------------------------ | ------------------------------------------------ |
| **GET**    | `/sender-accounts`                               | List all sender accounts (paginated, filterable) |
| **GET**    | `/sender-accounts/{inbox_id}`                    | Get detailed sender account info                 |
| **DELETE** | `/sender-accounts/{inbox_id}`                    | Remove a sender account                          |
| **POST**   | `/sender-accounts/coldsend-native`               | Create a ColdSend Native inbox                   |
| **POST**   | `/sender-accounts/coldsend-native/bulk`          | Bulk create ColdSend Native inboxes (max 100)    |
| **POST**   | `/sender-accounts/smtp`                          | Create an SMTP inbox (BYOC)                      |
| **POST**   | `/sender-accounts/smtp/bulk`                     | Bulk create SMTP inboxes (max 100, async)        |
| **GET**    | `/sender-accounts/smtp/bulk/{job_id}/progress`   | Track bulk SMTP job progress                     |
| **POST**   | `/sender-accounts/bulk/delete`                   | Bulk delete sender accounts (async)              |
| **GET**    | `/sender-accounts/bulk/delete/{job_id}/progress` | Track bulk delete job progress                   |
| **POST**   | `/sender-accounts/{inbox_id}/test-email`         | Send a test email                                |
| **GET**    | `/sender-accounts/quotas`                        | Get per-inbox daily quota state for a campaign   |
| **GET**    | `/sender-accounts/daily-usage`                   | Get daily send counts for all inboxes in team    |

## List & Filter Sender Accounts

`GET /api/public/v1/sender-accounts` supports filtering and pagination:

```python theme={null}
response = requests.get(
    "https://api.coldsend.pro/api/public/v1/sender-accounts?inbox_type=GOOGLE_WORKSPACE&status=ACTIVE&page=1&limit=20",
    headers={"X-API-Key": api_key}
)
```

### Query Parameters

| Parameter    | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| `page`       | Page number (1-based, default: 1)                                            |
| `limit`      | Items per page (1-100, default: 20)                                          |
| `inbox_type` | Filter by type: `COLDSEND`, `GOOGLE_WORKSPACE`, `OUTLOOK_365`, `CUSTOM_SMTP` |
| `status`     | Filter by status: `ACTIVE`, `PAUSED`, `DISABLED`                             |
| `search`     | Search by email address                                                      |
| `sort_by`    | Sort field: `email_address`, `inbox_type`, `created_at`, `health_score`      |
| `sort_order` | Sort direction: `asc`, `desc`                                                |

### Response Format

```json theme={null}
{
  "success": true,
  "message": "Retrieved 3 sender accounts",
  "sender_accounts": [
    {
      "inbox_id": "750e8400-e29b-41d4-a716-446655440000",
      "email_address": "john@company.com",
      "display_name": "John Smith",
      "inbox_type": "GOOGLE_WORKSPACE",
      "overall_status": "ACTIVE",
      "daily_limit": 50,
      "emails_sent_today": 12,
      "health_score": 95.0,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
```

## Account Status

| Status       | Description                                    |
| ------------ | ---------------------------------------------- |
| **ACTIVE**   | Ready to use in campaigns                      |
| **PAUSED**   | Temporarily disabled, can be reactivated       |
| **DISABLED** | Cannot be used — may require re-authentication |

## Inbox Types

The API uses these `inbox_type` values consistently:

| Value              | Description                    |
| ------------------ | ------------------------------ |
| `COLDSEND`         | ColdSend Native managed inbox  |
| `GOOGLE_WORKSPACE` | Google Workspace via SMTP/IMAP |
| `OUTLOOK_365`      | Microsoft 365 via SMTP/IMAP    |
| `CUSTOM_SMTP`      | Any custom SMTP provider       |

## Next Steps

<CardGroup cols={2}>
  <Card title="Provider Configuration" icon="settings" href="/sender-accounts/providers">
    Detailed SMTP setup guides for Google Workspace, Microsoft 365, and custom providers.
  </Card>

  <Card title="Campaigns Overview" icon="mail" href="/campaigns/overview">
    Learn how to assign sender accounts to campaigns.
  </Card>
</CardGroup>