Docs/Campaigns

Campaigns API

Send bulk email campaigns to your subscribers with segmentation and tracking.

Overview

Campaigns are bulk email sends to your subscriber list. Use tags to segment your audience and track delivery, opens, and clicks.

High Throughput

500 emails/sec with BullMQ queuing.

Tag Segmentation

Target specific subscriber groups.

Async Processing

API returns immediately, emails queued.

Real-time Stats

Track opens, clicks, and bounces.

POST

/api/v1/campaigns/send

Send Campaign

Queue a bulk email campaign to subscribers. Returns immediately with a campaign ID for tracking.

Request Body

Parameter	Type	Required	Description
subject	string	Required	Email subject line (supports Handlebars)
from_name	string	Required	Sender display name
from_email	string	Required	Sender email (from verified domain)
html	string	Optional*	HTML content (required if no templateId)
templateId	uuid	Optional*	Saved template ID
name	string	Optional	Campaign name for tracking
tags	string[]	Optional	Filter subscribers by tags
variables	object	Optional	Global template variables
external_id	string	Optional	Your external system ID for correlation
metadata	object	Optional	Custom key-value pairs for your application

Subscriber personalization

Use {{first_name}}, {{email}}, and other subscriber fields in your templates. They're automatically populated for each recipient.

Example Request

bash

curl -X POST https://sendmailos.com/api/v1/campaigns/send \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "January Newsletter",
    "subject": "{{first_name}}, check out what'\''s new!",
    "from_name": "Your Company",
    "from_email": "[email protected]",
    "html": "<h1>Hi {{first_name}}!</h1><p>Here are this month'\''s updates...</p>",
    "tags": ["newsletter", "active"],
    "external_id": "rb_campaign_jan_2024",
    "metadata": {
      "campaign_type": "monthly",
      "source": "restaurantsboost"
    }
  }'

Response (202 Accepted)

json

{
  "success": true,
  "message": "Campaign queued with 1,234 subscribers",
  "campaignId": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "rb_campaign_jan_2024"
}

Tag Filtering

Use tags to segment your audience. When multiple tags are provided, subscribers must have ALL tags (AND logic).

Tags	Behavior
`[]` (empty)	Send to ALL subscribed subscribers
`["newsletter"]`	Send to subscribers with "newsletter" tag
`["premium", "active"]`	Send to subscribers with BOTH tags

javascript

// Example: Send to premium users who are active
{
  "subject": "Exclusive Premium Offer",
  "tags": ["premium", "active"],
  ...
}

// Example: Send to all subscribers
{
  "subject": "Company Announcement",
  "tags": [],  // or omit entirely
  ...
}

Safety Features

SendMailOS includes built-in safety monitors to protect your sender reputation.

Automatic Pause on High Bounce Rate

Campaigns are automatically paused if the bounce rate exceeds 10%. This protects your domain reputation and prevents blacklisting.

Rate Limiting

•Marketing emails: 500/sec (30,000/min) hard limit
•Emails are processed through BullMQ with automatic retries
•Failed emails are logged with detailed error information

Template Variables

Use Handlebars syntax for personalization. Subscriber fields are automatically available.

Variable	Description
{{email}}	Subscriber email address
{{first_name}}	Subscriber first name
{{last_name}}	Subscriber last name
{{unsubscribe_url}}	One-click unsubscribe link

html

<!-- Example template with personalization -->
<h1>Hi {{first_name}}!</h1>
<p>Thank you for being a valued subscriber.</p>
<p>
  <a href="{{unsubscribe_url}}">Unsubscribe</a>
</p>