SMTP credentials

Each campaign owns one or more SMTP credentials. The dispatcher rotates among enabled credentials when scheduling sends. IMAP fields are optional but enable reply detection.

Add a credential to a campaign

POST /campaigns/:campaign_id/smtp_credentials
Authorization: Bearer <key>
Content-Type: application/json

{
  "smtp_credential": {
    "label": "Backup",
    "smtp_host": "smtp.postmarkapp.com",
    "smtp_port": 587,
    "smtp_username": "...",
    "smtp_password": "...",
    "from_name": "Ada",
    "from_email": "[email protected]",
    "daily_limit": 100,
    "imap_host": "imap.gmail.com",
    "imap_port": 993,
    "imap_username": "...",
    "imap_password": "..."
  }
}

Field	Required	Notes
label	no	Display name.
smtp_host / smtp_port	yes	Provider-specific. 587 (STARTTLS) is typical.
smtp_username / smtp_password	yes	Credentials. Stored encrypted at rest.
from_name / from_email	yes	The visible “From: …” header.
daily_limit	yes	Max sends per UTC day for this credential. Step 2/3 sends don’t count against today’s cap.
imap_host / imap_port / imap_username / imap_password	no	If all four are set, reply detection runs every few minutes.

Response

{
  "id": "...",
  "from_email": "[email protected]",
  "from_name": "Ada",
  "smtp_host": "smtp.postmarkapp.com",
  "smtp_port": 587,
  "daily_limit": 100
}

Passwords are never returned in any response.

Update / Delete

PATCH /campaigns/:campaign_id/smtp_credentials/:id   { "smtp_credential": { "daily_limit": 500 } }
DELETE /campaigns/:campaign_id/smtp_credentials/:id

Re-enable an auto-disabled credential

The bounce-rate auto-disable sets disabled_at on credentials whose bounce rate exceeds the campaign’s threshold. Once you’ve cleaned up your list:

POST /campaigns/:campaign_id/smtp_credentials/:credential_id/reenable
Authorization: Bearer <key>

{ "id": "...", "from_email": "...", "status": "enabled" }

Errors

Status	Code	When
404	campaign_not_found	Unknown campaign or another account’s.
404	smtp_credential_not_found	Unknown credential id under that campaign.
422	validation_failed	Missing required fields, invalid daily_limit, etc.