Skip to main content
POST
/
api
/
v1
/
email-accounts
/
save
curl -X POST "https://server.smartlead.ai/api/v1/email-accounts/save?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_name": "John Doe",
    "from_email": "john@example.com",
    "user_name": "john@example.com",
    "password": "your_app_password",
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "imap_host": "imap.gmail.com",
    "imap_port": 993,
    "warmup_enabled": true,
    "total_warmup_per_day": 20,
    "daily_rampup": 2,
    "max_email_per_day": 50,
    "time_to_wait_in_mins": 5,
    "type": "GMAIL"
  }'

{
  "ok": true,
  "message": "Email account added successfully",
  "data": {
    "id": 123,
    "from_email": "john@example.com",
    "is_smtp_success": true,
    "is_imap_success": true,
    "warmup_details": {
      "status": "ACTIVE",
      "total_warmup_per_day": 20
    }
  }
}
Creates a new email account with SMTP and IMAP configuration. SmartLead will validate the connection and optionally enable email warmup. Supports both standard SMTP accounts and OAuth providers (Gmail, Outlook).

​
Query Parameters

​
api_key
string
required
Your SmartLead API key

​
Request Body

​
from_name
string
required
Display name for outgoing emails (e.g., “John Doe”)
​
from_email
string
required
Email address (must be valid email format)
​
user_name
string
required
SMTP username (usually the email address)
​
password
string
required
SMTP password or app-specific password
​
smtp_host
string
required
SMTP server hostname (e.g., “smtp.gmail.com”)
​
smtp_port
number
required
SMTP server port (common ports: 587 for TLS, 465 for SSL, 25 for plain)
​
imap_host
string
required
IMAP server hostname (e.g., “imap.gmail.com”)
​
imap_port
number
required
IMAP server port (common ports: 993 for SSL, 143 for plain)
​
warmup_enabled
boolean
required
Whether to enable email warmup for this account
​
id
number
Email account ID (only for updates, null for new accounts)
​
type
string
Email provider type. Valid values: GMAIL, OUTLOOK, SMTP
​
token
object
OAuth token object (for Gmail/Outlook OAuth accounts)
​
different_reply_to_address
string
Custom reply-to email address (if different from from_email)
​
imap_user_name
string
IMAP username (if different from SMTP username)
​
imap_password
string
IMAP password (if different from SMTP password)
​
max_email_per_day
number
Maximum emails allowed per day (including warmup and campaign emails)
​
custom_tracking_url
string
Custom domain for tracking links
​
bcc
string
BCC email address for all outgoing emails
​
time_to_wait_in_mins
number
Minimum time to wait between emails in minutes
​
signature
string
Email signature HTML
​
total_warmup_per_day
number
Number of warmup emails to send per day (if warmup_enabled is true)
​
daily_rampup
number
Daily increase in warmup email count
​
reply_rate_percentage
number
Target reply rate percentage for warmup emails
​
client_id
number
Client ID for multi-tenant accounts
​
is_suspended
boolean
Whether the account should be suspended upon creation
curl -X POST "https://server.smartlead.ai/api/v1/email-accounts/save?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_name": "John Doe",
    "from_email": "john@example.com",
    "user_name": "john@example.com",
    "password": "your_app_password",
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "imap_host": "imap.gmail.com",
    "imap_port": 993,
    "warmup_enabled": true,
    "total_warmup_per_day": 20,
    "daily_rampup": 2,
    "max_email_per_day": 50,
    "time_to_wait_in_mins": 5,
    "type": "GMAIL"
  }'

​
Response Codes

​
200
Success
Email account added successfully with connection validation
​
400
Bad Request
SMTP or IMAP connection failed - check credentials and server settings
​
401
Unauthorized
Invalid or missing API key
​
422
Validation Error
Missing required fields or invalid field values
​
500
Internal Server Error
Server error occurred
{
  "ok": true,
  "message": "Email account added successfully",
  "data": {
    "id": 123,
    "from_email": "john@example.com",
    "is_smtp_success": true,
    "is_imap_success": true,
    "warmup_details": {
      "status": "ACTIVE",
      "total_warmup_per_day": 20
    }
  }
}

​
Configuration Examples

{
  "from_name": "Your Name",
  "from_email": "your.email@gmail.com",
  "user_name": "your.email@gmail.com",
  "password": "your_app_specific_password",
  "smtp_host": "smtp.gmail.com",
  "smtp_port": 587,
  "imap_host": "imap.gmail.com",
  "imap_port": 993,
  "type": "GMAIL",
  "warmup_enabled": true
}

{
  "from_name": "Your Name",
  "from_email": "your.email@outlook.com",
  "user_name": "your.email@outlook.com",
  "password": "your_password",
  "smtp_host": "smtp.office365.com",
  "smtp_port": 587,
  "imap_host": "outlook.office365.com",
  "imap_port": 993,
  "type": "OUTLOOK",
  "warmup_enabled": true
}

{
  "from_name": "Your Name",
  "from_email": "you@yourdomain.com",
  "user_name": "you@yourdomain.com",
  "password": "your_password",
  "smtp_host": "smtp.yourdomain.com",
  "smtp_port": 587,
  "imap_host": "imap.yourdomain.com",
  "imap_port": 993,
  "type": "SMTP",
  "warmup_enabled": false
}

​
Usage Notes

For Gmail accounts, you must use an App Password rather than your regular Gmail password. Enable 2-factor authentication first, then generate an app password.
SmartLead automatically validates SMTP and IMAP connections upon adding an account. If validation fails, the account is still created but marked with connection errors that you can fix later.
Enable warmup for new email accounts to gradually build sender reputation. Set total_warmup_per_day to start with 10-20 emails and use daily_rampup of 2-5 to increase daily volume gradually.