Navigation
SuperSend

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,
      "health_score": 95,
      "status": "active",
      "signature": "<p>Best regards,<br>Sales Team</p>",
      "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:

ParameterTypeRequiredDescription
TeamIdstringNoFilter by team ID (if not provided, returns senders from all user's teams)
limitnumberNoResults per page (default: 50, max: 100)
offsetnumberNoPagination offset (default: 0)
searchstringNoSearch by email or send_as name
providerstringNoFilter by provider: smtp, outlook, google, missioninbox, supersend-relay, ss-private-smtp
disabledstringNoFilter by disabled status ("true" or "false")
warmstringNoFilter 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,
    "health_score": 95,
    "last_health_check": "2025-01-15T10:00:00Z",
    "domain_health": "good",
    "status": "active",
    "signature": "<p>Best regards,<br>Sales Team</p>",
    "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": "<p>New signature</p>",
    "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": "<p>New signature</p>",
    "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:

ParameterTypeRequiredDescription
send_asstringNoDisplay name and email (e.g., "Name <email@example.com>")
reply_tostringNoReply-to email address
signaturestringNoHTML signature
forward_tostringNoEmail to forward replies to
disabledbooleanNoDisable/enable sender
warmbooleanNoEnable/disable warming
max_per_daynumberNoMaximum emails per day (1-15000)
global_max_per_daynumberNoGlobal maximum per day (1-1000)
max_warm_per_daynumberNoMaximum warm emails per day (1-1000)
warm_email_rampnumberNoWarming ramp period in days (1-365)
mail_warm_minimumnumberNoMinimum warm emails per day (1-1000)
SenderProfileIdstringNoAssociate 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.

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)


FieldTypeDescription
emailstringEmail address
passwordstringEmail password or app password
smtp_hoststringSMTP server host
smtp_portnumberSMTP port (typically 587)
smtp_securebooleanUse TLS
imap_hoststringIMAP server host
imap_portnumberIMAP port (typically 993)
imap_tlsbooleanUse TLS for IMAP


General Settings


FieldTypeDescription
send_asstringDisplay name for emails
signaturestringHTML email signature
reply_tostringReply-to address
warmbooleanEnable warming
max_per_daynumberMax emails per day per campaign
global_max_per_daynumberMax emails per day total
max_warm_per_daynumberMax warming emails per day
disabledbooleanDisable sender


V1 vs V2 Endpoint Mapping

ActionV1 EndpointV2 Endpoint
ListGET /v1/sendersGET /v2/senders
GetGET /v1/sender/:id/detailsGET /v2/senders/:id
UpdatePUT /v1/sender/:id/settingsPATCH /v2/senders/:id
CreatePOST /v1/senderNot available in V2