Provider Configuration

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.

ColdSend Native inboxes don’t require SMTP/IMAP configuration — they’re managed entirely by ColdSend infrastructure. See Sender Accounts Overview for ColdSend Native setup.

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:

Access Security Settings

Go to Google Account Settings → Security → 2-Step Verification → App Passwords.

Generate App Password

Click “Select app” → Choose “Mail” → Enter a name like “ColdSend” → Click Generate.

Copy and Use Password

Copy the 16-character password and use it for both smtp_password and imap_password. Store it securely.

Example Request

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']}")

{
  "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"
}

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:

Access Admin Center

Go to Microsoft 365 Admin Center → Users → Active users → Select your user → Manage email apps.

Create App Password

Under Authentication → “Manage app passwords” → Click “Generate a new app password” → Label it “ColdSend API” → Click Add.

Use App Password

Use the generated password for both smtp_password and imap_password fields.

Some Microsoft 365 tenants may not support app passwords. If OAuth2 is enforced, you’ll need to use Microsoft’s OAuth2 flow instead.

Example Request

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

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:

Connect to SMTP server
Send EHLO command
Start TLS if enabled
Authenticate with credentials

IMAP Validation:

Connect to IMAP server
Login with credentials
Verify mailbox access

Failed validations return detailed error messages:

{
  "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

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.

Next Steps

Sender Accounts Overview

Learn about account types, listing, and lifecycle management.

Campaigns Overview

Learn how to assign sender accounts to campaigns.

Error Reference

Troubleshoot common account-related errors.

Getting Started

Authentication

Campaigns

Sender Accounts

Domains

Leads

Replies

Analytics

Reference

Compliance

Google Workspace

App Password Setup

Example Request

Microsoft 365 / Outlook

App Password Setup

Example Request

Custom SMTP

Common Port Configurations

Connection Validation

Common Validation Errors

Daily Sending Limits

Next Steps

Sender Accounts Overview

Campaigns Overview

Error Reference

​Google Workspace

​App Password Setup

​Example Request

​Microsoft 365 / Outlook

​App Password Setup

​Example Request

​Custom SMTP

​Common Port Configurations

​Connection Validation

​Common Validation Errors

​Daily Sending Limits

​Next Steps

Sender Accounts Overview

Campaigns Overview

Error Reference

Google Workspace

App Password Setup

Example Request

Microsoft 365 / Outlook

App Password Setup

Example Request

Custom SMTP

Common Port Configurations

Connection Validation

Common Validation Errors

Daily Sending Limits

Next Steps