Email Servers API

Email servers define the delivery infrastructure Broadcast uses to send your emails. Each server connects to a specific email provider and can be configured for broadcasts, sequences, transactional emails, or any combination.

Base URL

https://app.sendbroadcast.com/api/v1

Authentication

All requests require a Bearer token with the appropriate email server permissions. See Authentication for details.

The Email Server Object

Field Type Description
id integer Unique identifier
label string Display name for the server
vendor string Email provider (see supported vendors)
delivery_method string smtp or api
active boolean Whether the server is currently active
emails_per_hour integer Rate limit (emails per hour)
use_for_broadcasts boolean Use this server for broadcast emails
use_for_sequences boolean Use this server for sequence emails
use_for_transactionals boolean Use this server for transactional emails
include_unsubscribe_header boolean Include List-Unsubscribe header
include_unsubscribe_link boolean Include unsubscribe link in email body
use_custom_unsubscribe_link boolean Use a custom unsubscribe URL
custom_unsubscribe_link string Custom unsubscribe URL (if enabled)
smtp_address string SMTP server hostname
smtp_port integer SMTP server port
smtp_username string SMTP authentication username
smtp_password string SMTP password (redacted in responses)
smtp_authentication string SMTP auth type (e.g., plain, login)
smtp_enable_starttls_auto boolean Enable STARTTLS
aws_region string AWS region for SES
aws_ses_configuration_set string SES configuration set name
aws_access_key_id string AWS access key (redacted in responses)
aws_secret_access_key string AWS secret key (redacted in responses)
aws_setup_completed boolean Whether AWS SES setup is complete
postmark_api_token string Postmark server token (redacted)
inboxroad_api_token string Inboxroad API token (redacted)
inboxroad_sync_enabled boolean Enable Inboxroad synchronization
smtp_com_api_key string SMTP.com API key (redacted)
smtp_com_channel string SMTP.com channel identifier
email_headers array Custom email headers
connection_failed_at datetime Last connection failure timestamp
created_at datetime When the server was created (ISO 8601)
updated_at datetime When the server was last modified (ISO 8601)

Sensitive credentials (passwords, API keys, secret keys) are partially redacted in API responses. Only the first and last 4 characters are shown, with the middle replaced by bullet characters.

Example Email Server Object

{
  "id": 5,
  "label": "Production SES",
  "vendor": "aws_ses",
  "delivery_method": "api",
  "active": true,
  "emails_per_hour": 50000,
  "use_for_broadcasts": true,
  "use_for_sequences": true,
  "use_for_transactionals": false,
  "include_unsubscribe_header": true,
  "include_unsubscribe_link": true,
  "use_custom_unsubscribe_link": false,
  "custom_unsubscribe_link": null,
  "smtp_address": null,
  "smtp_port": null,
  "smtp_username": null,
  "smtp_password": null,
  "smtp_authentication": null,
  "smtp_enable_starttls_auto": null,
  "aws_region": "us-east-1",
  "aws_ses_configuration_set": "broadcast-production",
  "aws_access_key_id": "AKIA••••••••WXYZ",
  "aws_secret_access_key": "ab12••••••••yz89",
  "outbound_aws_access_key_id": null,
  "outbound_aws_secret_access_key": null,
  "aws_setup_completed": true,
  "postmark_api_token": null,
  "inboxroad_api_token": null,
  "inboxroad_sync_enabled": false,
  "smtp_com_api_key": null,
  "smtp_com_channel": null,
  "smtp_com_callback_setup": false,
  "email_headers": [
    { "id": 1, "key": "X-Campaign-Source", "value": "broadcast" }
  ],
  "connection_failed_at": null,
  "created_at": "2025-06-01T08:00:00Z",
  "updated_at": "2025-09-15T12:30:00Z"
}

Supported Vendors

Vendor Value Delivery Methods
AWS SES aws_ses API, SMTP
SendGrid sendgrid SMTP
Postmark postmark API, SMTP
Mailgun mailgun SMTP
Inboxroad inboxroad API
Resend resend SMTP
SMTP.com smtp_com API
Other (generic SMTP) other SMTP
Test Server test_server SMTP

List Email Servers

Retrieve all email servers for the current broadcast channel.

GET /api/v1/email_servers

Query Parameters

Parameter Type Required Description
limit integer No Maximum number of results to return
offset integer No Number of records to skip

Request

curl -X GET "https://app.sendbroadcast.com/api/v1/email_servers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "data": [
    {
      "id": 5,
      "label": "Production SES",
      "vendor": "aws_ses",
      "delivery_method": "api",
      "active": true,
      "emails_per_hour": 50000,
      "use_for_broadcasts": true,
      "use_for_sequences": true,
      "use_for_transactionals": false,
      "include_unsubscribe_header": true,
      "include_unsubscribe_link": true,
      "email_headers": [],
      "created_at": "2025-06-01T08:00:00Z",
      "updated_at": "2025-09-15T12:30:00Z"
    }
  ],
  "total": 1
}

Get an Email Server

Retrieve a single email server by its ID.

GET /api/v1/email_servers/:id

Path Parameters

Parameter Type Required Description
id integer Yes The email server ID

Request

curl -X GET "https://app.sendbroadcast.com/api/v1/email_servers/5" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response

Returns the full email server object with redacted credentials.

Create an Email Server

Add a new email server to the current broadcast channel.

POST /api/v1/email_servers

Request Body

Wrap all fields inside email_server. The required fields depend on the vendor and delivery method.

Field Type Required Description
label string Yes Display name
vendor string Yes Provider identifier (see supported vendors)
delivery_method string Yes smtp or api
smtp_address string For SMTP SMTP server hostname
smtp_port integer For SMTP SMTP server port
smtp_username string For SMTP SMTP username
smtp_password string For SMTP SMTP password
smtp_authentication string No Auth type (plain, login, cram_md5)
smtp_enable_starttls_auto boolean No Enable STARTTLS (default: true)
aws_region string For AWS SES AWS region
aws_access_key_id string For AWS SES AWS access key
aws_secret_access_key string For AWS SES AWS secret key
postmark_api_token string For Postmark Postmark server token
emails_per_hour integer No Rate limit
use_for_broadcasts boolean No Enable for broadcasts
use_for_sequences boolean No Enable for sequences
use_for_transactionals boolean No Enable for transactional emails

Request

curl -X POST "https://app.sendbroadcast.com/api/v1/email_servers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email_server": {
      "label": "Postmark Transactional",
      "vendor": "postmark",
      "delivery_method": "api",
      "postmark_api_token": "your-postmark-server-token",
      "emails_per_hour": 10000,
      "use_for_broadcasts": false,
      "use_for_sequences": false,
      "use_for_transactionals": true,
      "include_unsubscribe_header": false
    }
  }'

Response 201 Created

Returns the full email server object.

Update an Email Server

Update an existing email server’s configuration.

PATCH /api/v1/email_servers/:id

Request

curl -X PATCH "https://app.sendbroadcast.com/api/v1/email_servers/5" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email_server": {
      "emails_per_hour": 75000,
      "use_for_transactionals": true
    }
  }'

Response

Returns the updated email server object.

Delete an Email Server

Permanently remove an email server configuration.

DELETE /api/v1/email_servers/:id

Request

curl -X DELETE "https://app.sendbroadcast.com/api/v1/email_servers/5" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "message": "Email server deleted successfully"
}

Test Connection

Verify that the email server can connect to the provider. A successful test activates the server; a failure deactivates it and records the failure timestamp.

POST /api/v1/email_servers/:id/test_connection

Request

curl -X POST "https://app.sendbroadcast.com/api/v1/email_servers/5/test_connection" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Success Response

{
  "success": true,
  "message": "Connection successful"
}

Failure Response 422

{
  "success": false,
  "message": "Connection failed"
}

Custom Email Headers

Email servers support custom headers that are included with every email sent through that server. Headers are managed via nested attributes:

curl -X PATCH "https://app.sendbroadcast.com/api/v1/email_servers/5" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email_server": {
      "email_headers_attributes": [
        { "key": "X-Campaign-Source", "value": "broadcast" },
        { "key": "X-Environment", "value": "production" }
      ]
    }
  }'

To remove a header, include its id with _destroy: true:

{
  "email_server": {
    "email_headers_attributes": [
      { "id": 1, "_destroy": true }
    ]
  }
}

Error Responses

404 Not Found

{
  "error": "Email server not found"
}

422 Unprocessable Content

{
  "error": "Label can't be blank, Vendor can't be blank"
}

Required Permissions

Action Permission
List / Get email_servers_read
Create / Update / Delete / Test email_servers_write

Next: Opt-in Forms API – Manage subscription forms via API.