Skip to main content
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

SettingValue
inbox_typeGOOGLE_WORKSPACE
smtp_hostsmtp.gmail.com
smtp_port587
imap_hostimap.gmail.com
imap_port993
smtp_use_tlstrue
imap_use_ssltrue
Max Daily Limit2,000 emails/day

​
App Password Setup

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

Access Security Settings

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

Generate App Password

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

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

SettingValue
inbox_typeOUTLOOK_365
smtp_hostsmtp.office365.com
smtp_port587
imap_hostoutlook.office365.com
imap_port993
smtp_use_tlstrue
imap_use_ssltrue
Max Daily Limit5,000 emails/day

​
App Password Setup

For Microsoft 365 accounts with modern authentication:
1

Access Admin Center

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

Create App Password

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

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.
SettingValue
inbox_typeCUSTOM_SMTP
smtp_port587 (STARTTLS) or 465 (SSL)
imap_port993 (SSL) or 143 (STARTTLS)
Max Daily Limit100,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

PortProtocolUse Case
587SMTP + STARTTLSRecommended for most providers
465SMTP + SSLLegacy/implicit SSL
993IMAP + SSLStandard for most providers
143IMAP + STARTTLSLegacy/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: 
{
  "detail": "SMTP connection failed: Authentication failed"
}

​
Common Validation Errors

ErrorResolution
AUTH_FAILEDVerify credentials, regenerate app password
CONNECTION_FAILEDCheck network connectivity and server status
TIMEOUTCheck firewall rules for the SMTP/IMAP ports
HOST_NOT_FOUNDVerify hostname and DNS configuration
SSL_ERRORCheck SSL certificate and TLS settings

​
Daily Sending Limits

Start conservative and increase gradually:
Account AgeRecommended Daily Limit
0-2 weeks20-30 emails/day
2-4 weeks50-80 emails/day
4+ weeks80-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.