Email Accounts

Email accounts are the mailboxes your campaigns send from. Credentials (SMTP passwords, API keys, OAuth tokens) are never returned by the API.

Google and Microsoft accounts are connected through OAuth in the app (Settings → Email accounts). You can create SMTP and SendGrid accounts through the API.

The email account object

{
  "id": 2,
  "name": "Sales mailbox",
  "from_email": "sales@acme.com",
  "from_name": "Acme Sales",
  "type": "smtp",
  "is_default": true,
  "is_active": true,
  "daily_limit": 500,
  "sent_today": 132,
  "last_used_at": "...",
  "created_at": "...",
  "updated_at": "..."
}

type is one of smtp, sendgrid, google or microsoft.

Endpoints

Method	Path	Permission	Description
GET	/email-accounts	email_accounts:read	List accounts (paginated)
POST	/email-accounts	email_accounts:write	Create an SMTP or SendGrid account
GET	/email-accounts/{id}	email_accounts:read	Get an account
PUT	/email-accounts/{id}	email_accounts:write	Update an account (partial)
DELETE	/email-accounts/{id}	email_accounts:write	Delete an account. Returns 204.
POST	/email-accounts/{id}/test	email_accounts:write	Test the connection
POST	/email-accounts/{id}/set-default	email_accounts:write	Make it the default account
GET	/email-accounts/{id}/stats	email_accounts:read	Sending statistics
POST	/email-accounts/{id}/reset-counter	email_accounts:write	Reset sent_today to zero

List email accounts

GET /email-accounts returns only accounts in the authenticated token's workspace. Credentials are never included.

Parameter	Type	Default	Description
page	integer	1	Page number, starting at 1
per_page	integer	15	Results per page, from 1 to 100
search	string		Partial name, sender email or sender name
type	string		smtp, sendgrid, google or microsoft
is_active	boolean		Filter by active status
is_default	boolean		Filter by default status
sort	string	created_at	name, from_email, type, is_default, is_active, daily_limit, sent_today, last_used_at, created_at or updated_at
direction	string	desc	asc or desc

GET /api/v1/email-accounts?search=sales&type=smtp&is_active=1&sort=name&direction=asc&per_page=30

The response follows the pagination contract. Equal sort values are ordered consistently by account ID.

Create an account

Field	Rules
name	Required. Max 255 characters
type	Required. smtp or sendgrid
from_email	Required. Email address
from_name	Required. Max 255 characters
daily_limit	1–10000, default 500
is_active	boolean, default true
smtp_host, smtp_port, smtp_username, smtp_password	Required when type=smtp. smtp_port must be one of 25, 465, 587, 993, 995 or 2525
smtp_encryption	tls (default) or ssl
sendgrid_api_key	Required when type=sendgrid

{
  "name": "Sales mailbox",
  "type": "smtp",
  "from_email": "sales@acme.com",
  "from_name": "Acme Sales",
  "smtp_host": "smtp.acme.com",
  "smtp_port": 587,
  "smtp_username": "sales@acme.com",
  "smtp_password": "••••••••"
}

The first account you create in a workspace becomes the default.

201: { "data": EmailAccount }

Test the connection

POST /email-accounts/{id}/test

• 200: { "data": { "success": true, "message": "SMTP connection successful" } }
• 422: { "data": { "success": false, "message": "Connection failed. Please verify your credentials and try again." } }

Stats

{
  "data": {
    "sent_today": 132,
    "daily_limit": 500,
    "remaining_today": 368,
    "can_send_today": true,
    "total_sent": 18420,
    "sent_last_7_days": 2310,
    "sent_last_30_days": 9104,
    "last_used_at": "..."
  }
}

Delete

When you delete the default account, another account becomes the default. You can't delete your only account: that returns 403.