# Send bulk emails (mail merge)

Send the same email template to multiple recipients with personalization.

Mail merge functionality for:
- Newsletters with personalized greetings
- Marketing campaigns with custom variables
- Bulk transactional emails with recipient-specific data

Features:
- Template variables: Use {{variable}} syntax in subject, HTML, and text
- Per-recipient personalization via vars object
- Automatic variable substitution for each recipient
- Single template, many recipients
- File attachments (same for all recipients)
- Calendar invites (same for all recipients)

Limits:
- Recommended: Up to 10,000 recipients per call
- Each recipient gets their own personalized copy

Use cases:
- Newsletter campaigns: "Hi {{name}}, check out our new {{product}}..."
- Promotional emails with unique discount codes
- Event invitations with personalized details

Not for: Different emails to each recipient → Use /api/batch instead

Endpoint: POST /api/v1/bulk-send
Version: 1.0.0
Security: ApiKeyAuth

## Request fields (application/json):

  - `subject` (string, required)
    Email subject with optional variables {{name}}
    Example: "Hello {{name}}! Special offer inside"

  - `html` (string)
    HTML email body with variables
    Example: "<h1>Hi {{name}}</h1><p>Use code <strong>{{code}}</strong> for 20% off!</p>"

  - `text` (string)
    Plain text email body with variables
    Example: "Hi {{name}}, Use code {{code}} for 20% off!"

  - `from` (string)
    From email (must use verified domain, optional)
    Example: "hello@mail.yourdomain.com"

  - `domain` (string)
    Sending domain (optional - auto-extracted from from email if not provided).
If provided, must match the domain in from email address.
    Example: "mail.yourdomain.com"

  - `reply_to` (string)
    Reply-to address
    Example: "support@yourdomain.com"

  - `track_opens` (boolean)
    Enable open tracking (default: true)
    Example: true

  - `track_clicks` (boolean)
    Enable click tracking (default: true)
    Example: true

  - `tag` (string)
    Tag for organizing/filtering emails
    Example: "holiday-sale-2025"

  - `stream_type` (string)
    Stream type is locked to broadcast for bulk sending.
Bulk/mail merge emails are marketing/newsletter content and must use the broadcast stream to protect transactional IP reputation.
    Enum: "broadcast"

  - `attachments` (array)
    File attachments sent with every email (sent directly, not stored).
Same attachments sent to all recipients.

  - `attachments.filename` (string, required)
    Example: "newsletter.pdf"

  - `attachments.content` (string, required)
    Base64 encoded content

  - `attachments.contentType` (string, required)
    Example: "application/pdf"

  - `icalEvent` (string)
    iCal calendar event in RFC 5545 format (sent directly, not stored).
Same calendar invite sent to all recipients.

  - `recipients` (array, required)
    Array of recipients with personalization variables
    Example: [{"email":"john@example.com","vars":{"name":"John","code":"JOHN20"}},{"email":"jane@example.com","vars":{"name":"Jane","code":"JANE20"}}]

  - `recipients.email` (string, required)
    Recipient email address
    Example: "user@example.com"

  - `recipients.vars` (object)
    Variables for this recipient
    Example: {"name":"John Doe","code":"SAVE20","product":"Premium Plan"}

## Response 200 fields (application/json):

  - `success` (boolean)
    Example: true

  - `queued` (integer)
    Number of emails queued
    Example: 2

  - `results` (array)
    Array of queued email IDs

  - `results.email_id` (string)

  - `results.recipient` (string)

  - `results.message_id` (string)

  - `results.status` (string)
    Example: "queued"

## Response 400 fields (application/json):

  - `error` (string)

  - `message` (string)

## Response 401 fields (application/json):

  - `error` (string)

## Response 500 fields (application/json):

  - `error` (string)

  - `message` (string)