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
}'
import requests
API_KEY = "YOUR_API_KEY"
# Gmail OAuth account
payload = {
"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,
"time_to_wait_in_mins": 5
}
response = requests.post(
"https://server.smartlead.ai/api/v1/email-accounts/save-oauth",
params={"api_key": API_KEY},
json=payload
)
result = response.json()
if result.get('ok'):
print(f"OAuth account added successfully. ID: {result['data']['id']}")
const API_KEY = 'YOUR_API_KEY';
// Outlook OAuth account
const payload = {
from_name: 'Jane Smith',
from_email: 'jane@outlook.com',
username: 'jane@outlook.com',
type: 'OUTLOOK',
token: {
scope: 'https://outlook.office.com/.default',
token_type: 'Bearer',
access_token: 'EwBwA8l6BAAU...',
refresh_token: 'M.R3_BAY...',
expiry_date: 1732627200000
},
warmup_enabled: true,
use_whitelabel_credentials: true,
total_warmup_per_day: 15,
daily_rampup: 3,
max_email_per_day: 40
};
const response = await fetch(
`https://server.smartlead.ai/api/v1/email-accounts/save-oauth?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(`OAuth account added. ID: ${result.data.id}`);
}
{
"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
}
}
{
"message": "Invalid API Key"
}
{
"error": "type must be one of [GMAIL, OUTLOOK]"
}
{
"ok": false,
"message": "Invalid or expired OAuth token"
}
Email Account Management
Add OAuth Email Account
Connect Gmail or Outlook account using OAuth 2.0 with automatic token refresh
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
}'
import requests
API_KEY = "YOUR_API_KEY"
# Gmail OAuth account
payload = {
"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,
"time_to_wait_in_mins": 5
}
response = requests.post(
"https://server.smartlead.ai/api/v1/email-accounts/save-oauth",
params={"api_key": API_KEY},
json=payload
)
result = response.json()
if result.get('ok'):
print(f"OAuth account added successfully. ID: {result['data']['id']}")
const API_KEY = 'YOUR_API_KEY';
// Outlook OAuth account
const payload = {
from_name: 'Jane Smith',
from_email: 'jane@outlook.com',
username: 'jane@outlook.com',
type: 'OUTLOOK',
token: {
scope: 'https://outlook.office.com/.default',
token_type: 'Bearer',
access_token: 'EwBwA8l6BAAU...',
refresh_token: 'M.R3_BAY...',
expiry_date: 1732627200000
},
warmup_enabled: true,
use_whitelabel_credentials: true,
total_warmup_per_day: 15,
daily_rampup: 3,
max_email_per_day: 40
};
const response = await fetch(
`https://server.smartlead.ai/api/v1/email-accounts/save-oauth?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(`OAuth account added. ID: ${result.data.id}`);
}
{
"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
}
}
{
"message": "Invalid API Key"
}
{
"error": "type must be one of [GMAIL, OUTLOOK]"
}
{
"ok": false,
"message": "Invalid or expired OAuth token"
}
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
string
required
Your SmartLead API key
Request Body
string
required
Display name for outgoing emails
string
required
Email address (must match OAuth account)
string
required
Email username (typically same as from_email)
string
required
Provider type. Valid values:
GMAIL, OUTLOOKobject
required
OAuth token object obtained from provider
Show Token properties
Show Token properties
string
required
OAuth scopes granted (e.g., “https://mail.google.com/”)
string
required
Token type, must be
Bearerstring
OAuth access token
string
OAuth refresh token for automatic renewal
number
required
Token expiry timestamp (Unix timestamp in milliseconds)
string
OpenID Connect ID token (optional)
string
Token expiry ISO string (optional)
number
Seconds until token expires (optional)
number
Extended expiry time for Microsoft tokens (optional)
boolean
required
Whether to enable email warmup for this account
boolean
required
Whether to use whitelabel OAuth credentials. Must be
true or falsenumber
Email account ID (only for updates, null for new accounts)
number
Maximum emails allowed per day (including warmup and campaigns)
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 per day (if warmup_enabled is true)
number
Daily increase in warmup email count
number
Target reply rate percentage for warmup
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
}'
import requests
API_KEY = "YOUR_API_KEY"
# Gmail OAuth account
payload = {
"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,
"time_to_wait_in_mins": 5
}
response = requests.post(
"https://server.smartlead.ai/api/v1/email-accounts/save-oauth",
params={"api_key": API_KEY},
json=payload
)
result = response.json()
if result.get('ok'):
print(f"OAuth account added successfully. ID: {result['data']['id']}")
const API_KEY = 'YOUR_API_KEY';
// Outlook OAuth account
const payload = {
from_name: 'Jane Smith',
from_email: 'jane@outlook.com',
username: 'jane@outlook.com',
type: 'OUTLOOK',
token: {
scope: 'https://outlook.office.com/.default',
token_type: 'Bearer',
access_token: 'EwBwA8l6BAAU...',
refresh_token: 'M.R3_BAY...',
expiry_date: 1732627200000
},
warmup_enabled: true,
use_whitelabel_credentials: true,
total_warmup_per_day: 15,
daily_rampup: 3,
max_email_per_day: 40
};
const response = await fetch(
`https://server.smartlead.ai/api/v1/email-accounts/save-oauth?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(`OAuth account added. ID: ${result.data.id}`);
}
Response Codes
Success
OAuth email account added successfully
Bad Request
Invalid OAuth token or connection validation failed
Unauthorized
Invalid or missing API key
Validation Error
Missing required fields or invalid type value
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
}
}
{
"message": "Invalid API Key"
}
{
"error": "type must be one of [GMAIL, OUTLOOK]"
}
{
"ok": false,
"message": "Invalid or expired OAuth token"
}
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.All2
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.
Related Endpoints
- Add SMTP Email Account - For non-OAuth accounts
- Update Email Account
- Get All Email Accounts
