Send a single email

Request

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

Domain selection: If you provide from, MailerLogic uses the domain part of that address as the sending domain unless domain is explicitly supplied. If from is omitted, MailerLogic uses your first verified domain.

Stream enforcement: The endpoint defaults to transactional. MailerLogic monitors repeated single-recipient sends for deterministic bulk-like behavior. Accepted traffic declared transactional that matches this pattern may be reclassified to broadcast to protect transactional IP reputation. Hard velocity or quota limits are still rejected with 429.

Idempotent retries: Pass an Idempotency-Key header (or idempotency_key body field) with a unique value per logical send. If the request is retried with the same key within 24 hours, the original response is returned with an X-Idempotent-Replay: true header and no duplicate email is sent. A retry that arrives while the original request is still processing receives 409 Conflict — wait and retry. Keys are scoped to your account. Responses with 5xx status are not stored, so failed requests can be retried safely with the same key.

Security

ApiKeyAuth

Headers

Idempotency-Keystring, <= 255 characters

Unique key for safe retries. Retrying with the same key within 24 hours replays the original response instead of sending a duplicate email.

Example:order-12345-receipt

Bodyapplication/jsonrequired

domainstring

Sending domain. Optional when from is provided; otherwise auto-selects the first verified domain.

Example:"mail.yourdomain.com"

fromstring or object

One of:

From email address, or an object with email and optional name. Defaults to noreply@domain when omitted.

string (email)

from_namestring

Display name for the sender when from is a string. Ignored when from.name is provided.

Example:"Your Company"

tostring, (email)required

Recipient email address

Example:"user@example.com"

reply_tostring, (email)

Reply-to email address

Example:"support@yourdomain.com"

ccArray of strings, (email)

CC recipients

Example:

[
  "manager@example.com"
]

bccArray of strings, (email)

BCC recipients (hidden from other recipients)

Example:

[
  "archive@yourdomain.com"
]

subjectstringrequired

Email subject line

Example:"Welcome to our platform!"

preview_textstring

Preview/preheader text shown in email clients next to subject (40-130 characters recommended). Appears in inbox list view before opening the email. Also called "preheader text".

Example:"Get started with your account in just a few clicks"

htmlstring

HTML email body. Supports dynamic placeholders:

Built-in Placeholders:

{{unsubscribe}} - Automatically replaced with secure unsubscribe link

Example:

<p>Don't want emails? <a href="{{unsubscribe}}">Unsubscribe</a></p>

The system automatically:

Replaces {{unsubscribe}} with unique, secure URL
Adds List-Unsubscribe headers for one-click unsubscribe
Tracks unsubscribes per domain

Example:"<h1>Welcome!</h1><p>Thanks for signing up.</p><p><a href=\"{{unsubscribe}}\">Unsubscribe</a></p>"

textstring

Plain text email body (fallback for non-HTML clients). Supports the same placeholders as HTML:

Built-in Placeholders:

{{unsubscribe}} - Automatically replaced with secure unsubscribe link

Example:

Unsubscribe: {{unsubscribe}}

Auto-generation: If you provide html but omit text, the platform automatically generates a clean plain-text version from your HTML before sending. The email is then delivered as multipart/alternative (text/plain + text/html), which improves deliverability and avoids spam filter penalties for HTML-only messages.

Providing your own text is still recommended for full control over accessibility and plain-text client rendering.

Example:"Welcome! Thanks for signing up.\n\nUnsubscribe: {{unsubscribe}}"

track_opensboolean

Enable open tracking (default: account setting)

Example:true

track_clicksboolean

Enable click tracking (default: account setting)

Example:true

headersobject

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"
}

tagstring

Tag for organizing emails (for analytics, not routing)

Example:"welcome-series"

stream_typestring

IP stream type for routing (default: transactional)

transactional: High-priority emails (passwords, confirmations, receipts)
broadcast: Marketing campaigns and newsletters (receives campaign-level bounce monitoring)
shared: General purpose emails

Campaign Tracking: Emails with stream_type: broadcast are automatically grouped into campaign sessions for bounce rate monitoring and auto-pause protection.

Declaring transactional is not an IP-pool bypass. Repeated bulk-like use of /send may be routed as broadcast; inspect stream_type and stream_reclassified in the response.

Default:"transactional"

Enum:"transactional""broadcast""shared"

Example:"transactional"

metadataobject

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"
}

attachmentsArray of objects

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"
  }
]

icalEventstring

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\nDTST

curl -i -X POST \
  https://api.mailerlogic.net/api/v1/send \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-12345-receipt' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "to": "user@example.com",
    "subject": "Welcome to our platform!",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
    "text": "Welcome! Thanks for signing up."
  }'

Responses

Email queued successfully

Bodyapplication/json

tostring, (email)

Recipient email address

Example:"user@example.com"

submitted_atstring, (date-time)

ISO 8601 timestamp when email was queued

Example:"2024-01-15T10:30:00Z"

message_idstring

RFC 5322 Message-ID header value

Example:"<650e8400-e29b-41d4-a716-446655440000@mail.yourdomain.com>"

email_idstring, (uuid)

Unique email ID for tracking

Example:"650e8400-e29b-41d4-a716-446655440000"

statusstring

Current email status

Value:"queued"

messagestring

Success message

stream_typestring

Effective stream used for queue and IP routing.

Enum:"transactional""broadcast""shared"

stream_reclassifiedboolean

True when MailerLogic changed the requested stream based on sending behavior.

stream_reclassification_reasonstring or null

Example:"bulk_like_transactional_pattern"

Response

{
  "to": "user@example.com",
  "submitted_at": "2024-03-15T14:30:00Z",
  "message_id": "<550e8400-e29b-41d4-a716-446655440000@mail.yourdomain.com>",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Email queued for delivery",
  "stream_type": "transactional",
  "stream_reclassified": false,
  "stream_reclassification_reason": null
}