Skip to main content
POST
/
api
/
v1
/
email-accounts
/
save-oauth
curl -X POST "https://server.smartlead.ai/api/v1/email-accounts/save-oauth?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_name": "John Doe",
    "from_email": "john@gmail.com",
    "username": "john@gmail.com",
    "type": "GMAIL",
    "token": {
      "scope": "https://mail.google.com/",
      "token_type": "Bearer",
      "access_token": "ya29.a0AfH6SMBx...",
      "refresh_token": "1//0gvJf9X...",
      "expiry_date": 1732627200000
    },
    "warmup_enabled": true,
    "use_whitelabel_credentials": true,
    "total_warmup_per_day": 20,
    "daily_rampup": 2,
    "max_email_per_day": 50
  }'

{
  "ok": true,
  "message": "OAuth account added successfully",
  "data": {
    "id": 123,
    "from_email": "john@gmail.com",
    "type": "GMAIL",
    "is_smtp_success": true,
    "is_imap_success": true
  }
}
Adds an OAuth-authenticated email account (Gmail or Outlook). SmartLead manages token refresh automatically. Use this endpoint after obtaining OAuth tokens from the respective provider.

​
Query Parameters

​
api_key
string
required
Your SmartLead API key

​
Request Body

​
from_name
string
required
Display name for outgoing emails
​
from_email
string
required
Email address (must match OAuth account)
​
username
string
required
Email username (typically same as from_email)
​
type
string
required
Provider type. Valid values: GMAIL, OUTLOOK
​
token
object
required
OAuth token object obtained from provider
​
warmup_enabled
boolean
required
Whether to enable email warmup for this account
​
use_whitelabel_credentials
boolean
required
Whether to use whitelabel OAuth credentials. Must be true or false
​
id
number
Email account ID (only for updates, null for new accounts)
​
max_email_per_day
number
Maximum emails allowed per day (including warmup and campaigns)
​
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 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
​
client_id
number
Client ID for multi-tenant accounts
curl -X POST "https://server.smartlead.ai/api/v1/email-accounts/save-oauth?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_name": "John Doe",
    "from_email": "john@gmail.com",
    "username": "john@gmail.com",
    "type": "GMAIL",
    "token": {
      "scope": "https://mail.google.com/",
      "token_type": "Bearer",
      "access_token": "ya29.a0AfH6SMBx...",
      "refresh_token": "1//0gvJf9X...",
      "expiry_date": 1732627200000
    },
    "warmup_enabled": true,
    "use_whitelabel_credentials": true,
    "total_warmup_per_day": 20,
    "daily_rampup": 2,
    "max_email_per_day": 50
  }'

​
Response Codes

​
200
Success
OAuth email account added successfully
​
400
Bad Request
Invalid OAuth token or connection validation failed
​
401
Unauthorized
Invalid or missing API key
​
422
Validation Error
Missing required fields or invalid type value
​
500
Internal Server Error
Server error occurred
{
  "ok": true,
  "message": "OAuth account added successfully",
  "data": {
    "id": 123,
    "from_email": "john@gmail.com",
    "type": "GMAIL",
    "is_smtp_success": true,
    "is_imap_success": true
  }
}

​
OAuth Flow

1

Obtain OAuth tokens from provider

Use Google or Microsoft OAuth flow to obtain access and refresh tokens with appropriate mail scopes.
Gmail Scope Required: https://mail.google.com/Outlook Scope Required: https://outlook.office.com/.default or https://outlook.office.com/SMTP.Send https://outlook.office.com/IMAP.AccessAsUser.All
2

Call this endpoint with tokens

Send the OAuth tokens and account information to this endpoint. SmartLead will validate the connection.
3

Enable warmup if needed

Set warmup_enabled: true and configure warmup parameters to gradually build sender reputation.

​
Usage Notes

OAuth tokens must be fresh and have the correct mail scopes. Expired tokens will cause connection failures.
Use use_whitelabel_credentials: true to leverage SmartLead’s OAuth app for Gmail/Outlook. This simplifies the OAuth flow as you don’t need to create your own OAuth application.
SmartLead automatically refreshes expired OAuth tokens using the refresh_token. Ensure the refresh_token is included in the token object.