Add SMTP Email Account

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

import requests

API_KEY = "YOUR_API_KEY"

payload = {
    "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",
    "signature": "<p>Best regards,<br>John</p>"
}

response = requests.post(
    "https://server.smartlead.ai/api/v1/email-accounts/save",
    params={"api_key": API_KEY},
    json=payload
)

result = response.json()
if result.get('ok'):
    print(f"Email account added successfully. ID: {result['data']['id']}")
else:
    print(f"Error: {result.get('message')}")

const API_KEY = 'YOUR_API_KEY';

const payload = {
  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',
  signature: '<p>Best regards,<br>John</p>'
};

const response = await fetch(
  `https://server.smartlead.ai/api/v1/email-accounts/save?api_key=${API_KEY}`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  }
);

const result = await response.json();
if (result.ok) {
  console.log(`Email account added successfully. ID: ${result.data.id}`);
} else {
  console.log(`Error: ${result.message}`);
}

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

{
  "ok": false,
  "message": "SMTP connection failed",
  "error": "Invalid credentials"
}

{
  "message": "Invalid API Key"
}

{
  "error": "from_name is required"
}

POST

api

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

import requests

API_KEY = "YOUR_API_KEY"

payload = {
    "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",
    "signature": "<p>Best regards,<br>John</p>"
}

response = requests.post(
    "https://server.smartlead.ai/api/v1/email-accounts/save",
    params={"api_key": API_KEY},
    json=payload
)

result = response.json()
if result.get('ok'):
    print(f"Email account added successfully. ID: {result['data']['id']}")
else:
    print(f"Error: {result.get('message')}")

const API_KEY = 'YOUR_API_KEY';

const payload = {
  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',
  signature: '<p>Best regards,<br>John</p>'
};

const response = await fetch(
  `https://server.smartlead.ai/api/v1/email-accounts/save?api_key=${API_KEY}`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  }
);

const result = await response.json();
if (result.ok) {
  console.log(`Email account added successfully. ID: ${result.data.id}`);
} else {
  console.log(`Error: ${result.message}`);
}

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

{
  "ok": false,
  "message": "SMTP connection failed",
  "error": "Invalid credentials"
}

{
  "message": "Invalid API Key"
}

{
  "error": "from_name is required"
}

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

string

required

Your SmartLead API key

Request Body

string

required

Display name for outgoing emails (e.g., “John Doe”)

string

required

Email address (must be valid email format)

string

required

SMTP username (usually the email address)

string

required

SMTP password or app-specific password

string

required

SMTP server hostname (e.g., “smtp.gmail.com”)

number

required

SMTP server port (common ports: 587 for TLS, 465 for SSL, 25 for plain)

string

required

IMAP server hostname (e.g., “imap.gmail.com”)

number

required

IMAP server port (common ports: 993 for SSL, 143 for plain)

boolean

required

Whether to enable email warmup for this account

number

Email account ID (only for updates, null for new accounts)

string

Email provider type. Valid values: GMAIL, OUTLOOK, SMTP

object

OAuth token object (for Gmail/Outlook OAuth accounts)

Show Token properties

string

required

OAuth scope granted

string

OAuth access token

string

OAuth refresh token

string

OAuth ID token

number

required

Token expiry timestamp

string

Custom reply-to email address (if different from from_email)

string

IMAP username (if different from SMTP username)

string

IMAP password (if different from SMTP password)

number

Maximum emails allowed per day (including warmup and campaign emails)

string

Custom domain for tracking links

string

BCC email address for all outgoing emails

number

Minimum time to wait between emails in minutes

string

Email signature HTML

number

Number of warmup emails to send per day (if warmup_enabled is true)

number

Daily increase in warmup email count

number

Target reply rate percentage for warmup emails

number

Client ID for multi-tenant accounts

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

import requests

API_KEY = "YOUR_API_KEY"

payload = {
    "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",
    "signature": "<p>Best regards,<br>John</p>"
}

response = requests.post(
    "https://server.smartlead.ai/api/v1/email-accounts/save",
    params={"api_key": API_KEY},
    json=payload
)

result = response.json()
if result.get('ok'):
    print(f"Email account added successfully. ID: {result['data']['id']}")
else:
    print(f"Error: {result.get('message')}")

const API_KEY = 'YOUR_API_KEY';

const payload = {
  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',
  signature: '<p>Best regards,<br>John</p>'
};

const response = await fetch(
  `https://server.smartlead.ai/api/v1/email-accounts/save?api_key=${API_KEY}`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  }
);

const result = await response.json();
if (result.ok) {
  console.log(`Email account added successfully. ID: ${result.data.id}`);
} else {
  console.log(`Error: ${result.message}`);
}

Response Codes

Success

Email account added successfully with connection validation

Bad Request

SMTP or IMAP connection failed - check credentials and server settings

Unauthorized

Invalid or missing API key

Validation Error

Missing required fields or invalid field values

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

{
  "ok": false,
  "message": "SMTP connection failed",
  "error": "Invalid credentials"
}

{
  "message": "Invalid API Key"
}

{
  "error": "from_name is required"
}

Configuration Examples

Gmail Configuration

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

Outlook/Office 365 Configuration

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

Custom SMTP Configuration

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

Add OAuth Email Account - For OAuth-based Gmail/Outlook
Get All Email Accounts
Update Warmup Settings

Get Email Account by ID Add OAuth Email Account

⌘I

Campaign Management

Campaign Leads

Campaign Webhooks

Campaign Statistics

Lead Management

Lead Notes

Lead Tasks

Lead Tags

Lead Lists

Email Account Management

Email Account Tags

Master Inbox

Smart Delivery

Smart Senders

Webhooks

Global Analytics

Utilities

Client Management

Smart Prospect

Query Parameters

Request Body

Response Codes

Configuration Examples

Usage Notes

​Query Parameters

​Request Body

​Response Codes

​Configuration Examples

​Usage Notes

​Related Endpoints

Query Parameters

Request Body

Response Codes

Configuration Examples

Usage Notes

Related Endpoints