Campaigns

Retrieve campaign details and performance statistics. Campaigns are created and managed through the TopMail dashboard.

GET

/campaigns

List all campaigns with summary stats.

Query Parameters

Name	Type	Required	Description
status	string	Optional	Filter by campaign status: "draft", "scheduled", "sending", "sent", or "paused".
limit	integer	Optional	Number of campaigns to return (default: 100, max: 1000).
offset	integer	Optional	Number of campaigns to skip for pagination (default: 0).

curl "https://api.topmail.so/api/v1/campaigns?status=sent&limit=10" \
  -H "Authorization: Bearer tm_live_abc123"

GET

/campaigns/:id

Retrieve a single campaign with detailed performance stats and rates.

curl https://api.topmail.so/api/v1/campaigns/CAMPAIGN_ID \
  -H "Authorization: Bearer tm_live_abc123"

{
  "data": {
    "id": "camp_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "January Newsletter",
    "subject": "Your January Update",
    "preview_text": "New features and product updates...",
    "status": "sent",
    "template": {
      "id": "t1a2b3c4",
      "name": "Monthly Newsletter"
    },
    "list": {
      "id": "l1a2b3c4",
      "name": "Newsletter Subscribers"
    },
    "segment": null,
    "stats": {
      "queued": 0,
      "sent": 1200,
      "delivered": 1185,
      "bounced": 15,
      "complained": 2,
      "opens": 980,
      "unique_opens": 450,
      "clicks": 340,
      "unique_clicks": 120,
      "unsubscribes": 5,
      "conversions": 18
    },
    "rates": {
      "delivery_rate": "98.75",
      "open_rate": "37.97",
      "click_rate": "10.13",
      "bounce_rate": "1.25",
      "unsubscribe_rate": "0.42"
    },
    "scheduled_at": null,
    "sent_at": "2025-01-15T09:00:00.000Z",
    "created_at": "2025-01-10T14:00:00.000Z",
    "updated_at": "2025-01-15T09:05:00.000Z"
  }
}

Stats Fields

Name	Type	Required	Description
queued	integer	Optional	Emails still in the send queue.
sent	integer	Optional	Total emails sent (including delivered).
delivered	integer	Optional	Emails confirmed delivered by the recipient mail server.
bounced	integer	Optional	Emails that bounced (hard or soft).
complained	integer	Optional	Emails marked as spam by recipients.
opens	integer	Optional	Total open events (includes repeat opens).
unique_opens	integer	Optional	Unique recipients who opened the email.
clicks	integer	Optional	Total click events (includes repeat clicks).
unique_clicks	integer	Optional	Unique recipients who clicked a link.
unsubscribes	integer	Optional	Recipients who unsubscribed from this campaign.
conversions	integer	Optional	Conversion events attributed to this campaign.

Rates Fields

All rates are returned as percentage strings with two decimal places.

Name	Type	Required	Description
delivery_rate	string	Optional	Percentage of sent emails that were delivered.
open_rate	string	Optional	Percentage of delivered emails that were opened (unique).
click_rate	string	Optional	Percentage of delivered emails with a link click (unique).
bounce_rate	string	Optional	Percentage of sent emails that bounced.
unsubscribe_rate	string	Optional	Percentage of delivered emails that led to an unsubscribe.