# Send a single email

Send a single transactional or marketing email via REST API.

Simple API for sending emails with:
- Automatic queuing and delivery
- Built-in tracking (opens & clicks)
- File attachments (PDF, ZIP, images, documents)
- Calendar invites (iCal/RFC 5545)
- Template variable support
- Custom headers
- Full bounce and complaint handling

Requirements:
- Verified sending domain
- Active customer account
- Valid API key

Auto-domain selection: If you don't specify a domain, we'll automatically use your first verified domain.

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

## Request fields (application/json):

  - `domain` (string)
    Sending domain (optional - auto-selects first verified domain if omitted)
    Example: "mail.yourdomain.com"

  - `from` (string)
    From email address (defaults to noreply@domain)
    Example: "hello@mail.yourdomain.com"

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

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

  - `cc` (array)
    CC recipients
    Example: ["manager@example.com"]

  - `bcc` (array)
    BCC recipients (hidden from other recipients)
    Example: ["archive@yourdomain.com"]

  - `subject` (string, required)
    Email subject line
    Example: "Welcome to our platform!"

  - `html` (string)
    HTML email body
    Example: "<h1>Welcome!</h1><p>Thanks for signing up.</p>"

  - `text` (string)
    Plain text email body (fallback for non-HTML clients)
    Example: "Welcome! Thanks for signing up."

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

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

  - `headers` (object)
    Custom email headers for the message.

Use cases:
- Add custom headers like X-Order-ID, X-User-ID
- Set Reply-To address
- Add tracking or reference headers
- Store structured data as JSON string

Webhook support: Headers are included in webhook payloads alongside metadata.

Note: Headers are sent with the email and included in webhooks. Use metadata for data that should NOT be sent in the email.
    Example: {"X-Campaign-ID":"campaign-123","X-User-ID":"user-456","Reply-To":"support@example.com"}

  - `tag` (string)
    Tag for organizing emails (for analytics, not routing)
    Example: "welcome-series"

  - `stream_type` (string)
    IP stream type for routing (default: shared)
- transactional: High-priority emails (passwords, confirmations)
- broadcast: Marketing campaigns and newsletters
- shared: General purpose emails
    Enum: "transactional", "broadcast", "shared"

  - `metadata` (object)
    Custom metadata (stored in database, NOT sent in email).

Use cases:
- Link emails to orders, users, or resources in your system
- Track campaign performance and ROI
- Store application-specific context
- Filter and analyze emails by custom attributes
- Pass through data to your webhook handlers

Webhook support: Metadata is included in all webhook events (delivered, bounced, opened, clicked, complained, unsubscribed).

Difference from headers: Metadata is never sent in the email, while headers are included in the email message.
    Example: {"user_id":"12345","order_id":"ord_789","campaign":"summer_sale","tier":"premium"}

  - `attachments` (array)
    File attachments (PDF, ZIP, images, documents).

Important: Attachments are sent directly through SMTP without storing on server.
Base64 encode your files and include them in the request.

- Max per file: 10 MB (configurable)
- Max total size: 25 MB (including HTML)
- Supported: All file types
    Example: [{"filename":"invoice.pdf","content":"JVBERi0xLjQK...","contentType":"application/pdf"},{"filename":"report.csv","content":"TmFtZSxFbWFpbC...","contentType":"text/csv"}]

  - `attachments.filename` (string, required)
    Display name for the attachment
    Example: "invoice-12345.pdf"

  - `attachments.content` (string, required)
    Base64 encoded file content
    Example: "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL..."

  - `attachments.contentType` (string, required)
    MIME type of the file
    Example: "application/pdf"

  - `attachments.encoding` (string)
    Content encoding (default is base64)
    Example: "base64"

  - `icalEvent` (string)
    iCal calendar event in RFC 5545 format for meeting invites.

Native calendar support - works with Gmail, Outlook, Apple Mail:
- Gmail: Shows "Add to Calendar" button
- Outlook: Shows Accept/Decline/Tentative buttons
- Apple Mail: Shows "Add to Calendar" button

Implementation: Sends as both text/calendar MIME alternative
AND invite.ics attachment for maximum compatibility.

Important: Event is sent directly, not stored on server.
    Example: "BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//YourApp//Calendar//EN\nMETHOD:REQUEST\nCALSCALE:GREGORIAN\nBEGIN:VEVENT\nUID:meeting-123@yourdomain.com\nDTSTAMP:20250127T120000Z\nDTSTART:20250128T140000Z\nDTEND:20250128T150000Z\nSUMMARY:Team Meeting\nDESCRIPTION:Discuss Q1 goals\nLOCATION:Conference Room A\nORGANIZER;CN=Manager:mailto:manager@yourdomain.com\nATTENDEE;CN=Employee;RSVP=TRUE:mailto:employee@example.com\nSTATUS:CONFIRMED\nSEQUENCE:0\nBEGIN:VALARM\nTRIGGER:-PT15M\nACTION:DISPLAY\nDESCRIPTION:Reminder\nEND:VALARM\nEND:VEVENT\nEND:VCALENDAR\n"

## Response 200 fields (application/json):

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

  - `submitted_at` (string)
    ISO 8601 timestamp when email was queued
    Example: "2024-01-15T10:30:00Z"

  - `message_id` (string)
    RFC 5322 Message-ID header value
    Example: "<650e8400-e29b-41d4-a716-446655440000@mail.yourdomain.com>"

  - `email_id` (string)
    Unique email ID for tracking
    Example: "650e8400-e29b-41d4-a716-446655440000"

  - `status` (string)
    Current email status
    Enum: "queued"

  - `message` (string)
    Success message

## Response 400 fields (application/json):

  - `error` (string)

  - `message` (string)

## Response 403 fields (application/json):

  - `error` (string)

  - `message` (string)

  - `reason` (string)

## Response 404 fields (application/json):

  - `error` (string)

  - `message` (string)

## Response 500 fields (application/json):

  - `error` (string)

  - `message` (string)