Sender API

Interfaces to manage email senders

A Sender is an email account used to send outbound emails. Senders can be Gmail, Microsoft 365, or custom SMTP accounts.

ℹ️

V2 API Available

V2 provides standardized responses for sender endpoints.

List Senders

Get all senders for your organization.

V2 API (Recommended)

bash

curl -X GET 'https://api.supersend.io/v2/senders?TeamId=xxx&limit=20&search=sales&provider=smtp&disabled=false&warm=true' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": [ { "id": "sender-uuid", "email": "sales@example.com", "send_as": "Sales Team <sales@example.com>", "reply_to": "support@example.com", "provider": "smtp", "domain": "example.com", "disabled": false, "warm": true, "warming_stage": 3, "max_per_day": 50, "global_max_per_day": 100, "max_warm_per_day": 25, "campaign_ramp_enabled": false, "campaign_ramp_first_send_date": null, "campaign_ramp_duration_days": null, "campaign_ramp_start_volume": null, "health_score": 95, "status": "active", "signature": "Best regards, Sales Team", "forward_to": null, "sender_profile_id": "profile-uuid", "team_id": "team-uuid", "created_at": "2025-01-01T00:00:00Z", "updated_at": "2025-01-15T00:00:00Z" } ], "pagination": { "total": 5, "limit": 20, "offset": 0, "hasMore": false }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Query Parameters:

Parameter	Type	Required	Description
`TeamId`	string	No	Filter by team ID (if not provided, returns senders from all user's teams)
`limit`	number	No	Results per page (default: 50, max: 100)
`offset`	number	No	Pagination offset (default: 0)
`search`	string	No	Search by email or send_as name
`provider`	string	No	Filter by provider: `smtp`, `outlook`, `google`, `missioninbox`, `supersend-relay`, `ss-private-smtp`
`disabled`	string	No	Filter by disabled status (`"true"` or `"false"`)
`warm`	string	No	Filter by warming status (`"true"` or `"false"`)

V1 API

bash

curl -X GET 'https://api.supersend.io/v1/senders?TeamId=xxx' \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Sender

Get details for a specific sender.

V2 API (Recommended)

bash

curl -X GET 'https://api.supersend.io/v2/senders/sender-uuid' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": { "id": "sender-uuid", "email": "sales@example.com", "send_as": "Sales Team <sales@example.com>", "reply_to": "support@example.com", "provider": "smtp", "domain": "example.com", "disabled": false, "manually_disabled": false, "warm": true, "warming_stage": 3, "warm_start_date": "2025-01-01T00:00:00Z", "max_per_day": 50, "global_max_per_day": 100, "max_warm_per_day": 25, "warm_email_ramp": 30, "mail_warm_minimum": 5, "campaign_ramp_enabled": false, "campaign_ramp_first_send_date": null, "campaign_ramp_duration_days": null, "campaign_ramp_start_volume": null, "health_score": 95, "last_health_check": "2025-01-15T10:00:00Z", "domain_health": "good", "status": "active", "signature": "Best regards, Sales Team", "forward_to": null, "imap_disabled": false, "smtp_host": "smtp.gmail.com", "smtp_port": 587, "smtp_secure": false, "imap_host": "imap.gmail.com", "imap_port": 993, "imap_tls": true, "sent_mailbox": "Sent", "inbox": "INBOX", "spam_folder": "Spam", "sender_profile": { "id": "profile-uuid", "name": "Sales Profile" }, "team": { "id": "team-uuid", "name": "Sales Team" }, "team_id": "team-uuid", "created_at": "2025-01-01T00:00:00Z", "updated_at": "2025-01-15T00:00:00Z" }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V1 API

bash

curl -X GET 'https://api.supersend.io/v1/sender/sender-uuid/details' \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Sender

Update sender settings.

V2 API (Recommended)

bash

curl -X PATCH 'https://api.supersend.io/v2/senders/sender-uuid' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "send_as": "Updated Name <sales@example.com>", "reply_to": "support@example.com", "signature": "New signature", "forward_to": "admin@example.com", "disabled": false, "warm": true, "max_per_day": 75, "global_max_per_day": 150, "max_warm_per_day": 30, "warm_email_ramp": 45, "mail_warm_minimum": 10, "SenderProfileId": "profile-uuid" }'

# Response (200 OK) { "success": true, "data": { "id": "sender-uuid", "email": "sales@example.com", "send_as": "Updated Name <sales@example.com>", "reply_to": "support@example.com", "provider": "smtp", "domain": "example.com", "disabled": false, "manually_disabled": false, "warm": true, "warming_stage": 3, "max_per_day": 75, "global_max_per_day": 150, "max_warm_per_day": 30, "warm_email_ramp": 45, "mail_warm_minimum": 10, "health_score": 95, "status": "active", "signature": "New signature", "forward_to": "admin@example.com", "sender_profile": { "id": "profile-uuid", "name": "Sales Profile", "timezone": "America/New_York" }, "team": { "id": "team-uuid", "name": "Sales Team" }, "team_id": "team-uuid", "created_at": "2025-01-01T00:00:00Z", "updated_at": "2025-01-15T00:00:00Z" }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Update Parameters:

Parameter	Type	Required	Description
`send_as`	string	No	Display name and email (e.g., "Name <email@example.com>")
`reply_to`	string	No	Reply-to email address
`signature`	string	No	HTML signature
`forward_to`	string	No	Email to forward replies to
`disabled`	boolean	No	Disable/enable sender
`warm`	boolean	No	Enable/disable warming
`max_per_day`	number	No	Maximum emails per day (1-15000)
`global_max_per_day`	number	No	Global maximum per day (1-1000)
`max_warm_per_day`	number	No	Maximum warm emails per day (1-1000)
`warm_email_ramp`	number	No	Warming ramp period in days (1-365)
`mail_warm_minimum`	number	No	Minimum warm emails per day (1-1000)
`campaign_ramp_enabled`	boolean	No	Enable campaign ramp-up (gradual increase from start volume to target)
`campaign_ramp_duration_days`	number	No	Days to reach target (1-365; required when ramp enabled)
`campaign_ramp_start_volume`	number	No	Daily limit on first campaign send day (required when ramp enabled)
`SenderProfileId`	string	No	Associate with sender profile (UUID or null)

Note: V2 Update does not support changing provider type or re-verifying credentials. Use V1 API for those advanced operations.

Campaign Ramp-Up

When campaign_ramp_enabled is true, the sender's effective daily limit starts at campaign_ramp_start_volume and increases linearly over campaign_ramp_duration_days until it reaches global_max_per_day. The ramp begins when the sender sends their first campaign email (not when the sender is created). Before the first send, the effective limit equals the start volume. After the first send, the limit increases each day until reaching the target.

campaign_ramp_first_send_date: Set automatically when the first campaign send occurs (read-only).

campaign_ramp_duration_days: Number of days from first send to reach the target (e.g. 30).

campaign_ramp_start_volume: Limit on day 0 (first send date). Must be between 1 and global_max_per_day.

V1 API

V1 has separate endpoints for connection settings and general settings:

Update Connection Settings:

bash

curl -X PUT 'https://api.supersend.io/sender/sender-uuid' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "TeamId": "xxx",
    "email": "new@example.com",
    "password": "xxx",
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587
  }'

Update General Settings:

bash

curl -X PUT 'https://api.supersend.io/v1/sender/sender-uuid/settings' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "TeamId": "xxx",
    "send_as": "Sales Team",
    "signature": "<p>Best regards</p>",
    "max_per_day": 50,
    "warm": true
  }'

Create Sender (V1 Only)

bash

curl -X POST 'https://api.supersend.io/v1/sender' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "TeamId": "xxx",
    "email": "sales@example.com",
    "password": "xxx",
    "send_as": "Sales Team",
    "signature": "<p>Best regards</p>",
    "warm": false,
    "global_max_per_day": 25
  }'

Sender Fields

Connection Settings (V1 only)

Field	Type	Description
`email`	string	Email address
`password`	string	Email password or app password
`smtp_host`	string	SMTP server host
`smtp_port`	number	SMTP port (typically 587)
`smtp_secure`	boolean	Use TLS
`imap_host`	string	IMAP server host
`imap_port`	number	IMAP port (typically 993)
`imap_tls`	boolean	Use TLS for IMAP

General Settings

Field	Type	Description
`send_as`	string	Display name for emails
`signature`	string	HTML email signature
`reply_to`	string	Reply-to address
`warm`	boolean	Enable warming
`max_per_day`	number	Max emails per day per campaign
`global_max_per_day`	number	Max emails per day total
`max_warm_per_day`	number	Max warming emails per day
`disabled`	boolean	Disable sender

V1 vs V2 Endpoint Mapping

Action	V1 Endpoint	V2 Endpoint
List	`GET /v1/senders`	`GET /v2/senders`
Get	`GET /v1/sender/:id/details`	`GET /v2/senders/:id`
Update	`PUT /v1/sender/:id/settings`	`PATCH /v2/senders/:id`
Create	`POST /v1/sender`	Not available in V2