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

# Provider Configuration

> Configure SMTP and IMAP settings for different email providers.

Each email provider has specific SMTP and IMAP settings. This guide covers configuration for supported providers when connecting via the `POST /api/public/v1/sender-accounts/smtp` endpoint.

<Info>
  ColdSend Native inboxes don't require SMTP/IMAP configuration — they're managed entirely by ColdSend infrastructure. See [Sender Accounts Overview](/sender-accounts/overview) for ColdSend Native setup.
</Info>

## Google Workspace

| Setting             | Value              |
| ------------------- | ------------------ |
| **inbox\_type**     | `GOOGLE_WORKSPACE` |
| **smtp\_host**      | `smtp.gmail.com`   |
| **smtp\_port**      | `587`              |
| **imap\_host**      | `imap.gmail.com`   |
| **imap\_port**      | `993`              |
| **smtp\_use\_tls**  | `true`             |
| **imap\_use\_ssl**  | `true`             |
| **Max Daily Limit** | 2,000 emails/day   |

### App Password Setup

Google requires app-specific passwords when 2FA is enabled:

<Steps>
  <Step title="Access Security Settings">
    Go to [Google Account Settings](https://myaccount.google.com) → **Security** → **2-Step Verification** → **App Passwords**.
  </Step>

  <Step title="Generate App Password">
    Click "Select app" → Choose "Mail" → Enter a name like "ColdSend" → Click **Generate**.
  </Step>

  <Step title="Copy and Use Password">
    Copy the 16-character password and use it for both `smtp_password` and `imap_password`. Store it securely.
  </Step>
</Steps>

### Example Request

```python theme={null}
import requests

api_key = "cs_live_your_api_key_here"
base_url = "https://api.coldsend.pro"

response = requests.post(
    f"{base_url}/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-16-char-app-password",
        "smtp_use_tls": True,
        "imap_host": "imap.gmail.com",
        "imap_port": 993,
        "imap_username": "outreach@company.com",
        "imap_password": "your-16-char-app-password",
        "imap_use_ssl": True
    }
)

sender_account = response.json()
print(f"Sender account created: {sender_account['inbox_id']}")
```

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "message": "SMTP inbox created successfully",
    "inbox_id": "750e8400-e29b-41d4-a716-446655440001",
    "email_address": "outreach@company.com",
    "display_name": "John Smith from Company",
    "inbox_type": "GOOGLE_WORKSPACE",
    "daily_limit": 50,
    "overall_status": "ACTIVE",
    "created_at": "2024-01-15T10:30:00Z"
  }
  ```
</ResponseExample>

## Microsoft 365 / Outlook

| Setting             | Value                   |
| ------------------- | ----------------------- |
| **inbox\_type**     | `OUTLOOK_365`           |
| **smtp\_host**      | `smtp.office365.com`    |
| **smtp\_port**      | `587`                   |
| **imap\_host**      | `outlook.office365.com` |
| **imap\_port**      | `993`                   |
| **smtp\_use\_tls**  | `true`                  |
| **imap\_use\_ssl**  | `true`                  |
| **Max Daily Limit** | 5,000 emails/day        |

### App Password Setup

For Microsoft 365 accounts with modern authentication:

<Steps>
  <Step title="Access Admin Center">
    Go to [Microsoft 365 Admin Center](https://admin.microsoft.com/) → **Users** → **Active users** → Select your user → **Manage email apps**.
  </Step>

  <Step title="Create App Password">
    Under **Authentication** → "Manage app passwords" → Click "Generate a new app password" → Label it "ColdSend API" → Click **Add**.
  </Step>

  <Step title="Use App Password">
    Use the generated password for both `smtp_password` and `imap_password` fields.
  </Step>
</Steps>

<Note>
  Some Microsoft 365 tenants may not support app passwords. If OAuth2 is enforced, you'll need to use Microsoft's OAuth2 flow instead.
</Note>

### Example Request

```python theme={null}
response = requests.post(
    f"{base_url}/api/public/v1/sender-accounts/smtp",
    headers={"X-API-Key": api_key},
    json={
        "email_address": "sales@company.com",
        "display_name": "Sales Team at Company",
        "inbox_type": "OUTLOOK_365",
        "daily_limit": 100,
        "smtp_host": "smtp.office365.com",
        "smtp_port": 587,
        "smtp_username": "sales@company.com",
        "smtp_password": "your-app-password",
        "smtp_use_tls": True,
        "imap_host": "outlook.office365.com",
        "imap_port": 993,
        "imap_username": "sales@company.com",
        "imap_password": "your-app-password",
        "imap_use_ssl": True
    }
)
```

## Custom SMTP

Use `CUSTOM_SMTP` for any email provider not listed above.

| Setting             | Value                           |
| ------------------- | ------------------------------- |
| **inbox\_type**     | `CUSTOM_SMTP`                   |
| **smtp\_port**      | `587` (STARTTLS) or `465` (SSL) |
| **imap\_port**      | `993` (SSL) or `143` (STARTTLS) |
| **Max Daily Limit** | 100,000 emails/day              |

```python theme={null}
response = requests.post(
    f"{base_url}/api/public/v1/sender-accounts/smtp",
    headers={"X-API-Key": api_key},
    json={
        "email_address": "outreach@mydomain.com",
        "display_name": "Outreach Team",
        "inbox_type": "CUSTOM_SMTP",
        "daily_limit": 100,
        "smtp_host": "mail.custom-provider.com",
        "smtp_port": 587,
        "smtp_username": "outreach@mydomain.com",
        "smtp_password": "your-smtp-password",
        "smtp_use_tls": True,
        "imap_host": "imap.custom-provider.com",
        "imap_port": 993,
        "imap_username": "outreach@mydomain.com",
        "imap_password": "your-imap-password",
        "imap_use_ssl": True
    }
)
```

### Common Port Configurations

| Port    | Protocol        | Use Case                       |
| ------- | --------------- | ------------------------------ |
| **587** | SMTP + STARTTLS | Recommended for most providers |
| **465** | SMTP + SSL      | Legacy/implicit SSL            |
| **993** | IMAP + SSL      | Standard for most providers    |
| **143** | IMAP + STARTTLS | Legacy/unencrypted start       |

## Connection Validation

When you create an SMTP inbox, ColdSend automatically validates both connections:

**SMTP Validation:**

1. Connect to SMTP server
2. Send EHLO command
3. Start TLS if enabled
4. Authenticate with credentials

**IMAP Validation:**

1. Connect to IMAP server
2. Login with credentials
3. Verify mailbox access

Failed validations return detailed error messages:

```json theme={null}
{
  "detail": "SMTP connection failed: Authentication failed"
}
```

### Common Validation Errors

| Error               | Resolution                                   |
| ------------------- | -------------------------------------------- |
| `AUTH_FAILED`       | Verify credentials, regenerate app password  |
| `CONNECTION_FAILED` | Check network connectivity and server status |
| `TIMEOUT`           | Check firewall rules for the SMTP/IMAP ports |
| `HOST_NOT_FOUND`    | Verify hostname and DNS configuration        |
| `SSL_ERROR`         | Check SSL certificate and TLS settings       |

## Daily Sending Limits

Start conservative and increase gradually:

| Account Age   | Recommended Daily Limit |
| ------------- | ----------------------- |
| **0-2 weeks** | 20-30 emails/day        |
| **2-4 weeks** | 50-80 emails/day        |
| **4+ weeks**  | 80-100+ emails/day      |

<Warning>
  Sending at maximum limits immediately can trigger spam filters. Always warm up new accounts gradually. The API validates your `daily_limit` against provider maximums at creation time.
</Warning>

## Next Steps

<CardGroup cols={3}>
  <Card title="Sender Accounts Overview" icon="inbox" href="/sender-accounts/overview">
    Learn about account types, listing, and lifecycle management.
  </Card>

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

  <Card title="Error Reference" icon="shield-alert" href="/reference/errors">
    Troubleshoot common account-related errors.
  </Card>
</CardGroup>