# MailerLogic API

Complete REST API for managing email delivery, tracking, and analytics.

Get started in minutes:
1. Get your API key from your customer dashboard
2. Send authenticated requests using the Bearer token
3. Start sending emails via SMTP or API

For detailed guides, see the Getting Started section in the navigation.


Version: 1.0.0

## Servers

Production API server
```
https://api.mailerlogic.io
```

EU Data Center (Coming Soon)
```
https://eu.api.mailerlogic.io
```

## Security

### BearerAuth

Customer API Key using Bearer token authentication.

Example:
```
Authorization: Bearer ml_live_1234567890abcdef...
```

Get your API key from your customer dashboard or use the `/api/customer/rotate-key` endpoint.


Type: http
Scheme: bearer
Bearer Format: API Key

### ApiKeyAuth

Customer API Key in X-API-Key header (used for SMTP and statistics endpoints).

Example:
```
X-API-Key: ml_live_1234567890abcdef...
```


Type: apiKey
In: header
Name: X-API-Key

## Download OpenAPI description

[MailerLogic API](https://developers.mailerlogic.com/_bundle/customer-api.openapi.yaml)

## Email Sending

Send transactional and marketing emails via REST API.
Simple API for sending individual emails with full tracking support.


### Send a single email

 - [POST /api/send](https://developers.mailerlogic.com/customer-api.openapi/email-sending/paths/~1api~1send/post.md): 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)
- 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.

### Send batch of different emails

 - [POST /api/batch](https://developers.mailerlogic.com/customer-api.openapi/email-sending/paths/~1api~1batch/post.md): Send up to 500 completely different emails in a single API call.

Batch sending where each email can have:
- Different recipient
- Different subject
- Different content
- Different settings

Perfect for sending multiple transactional emails at once (order confirmations, password resets, etc.).

Limits:
- Maximum 500 emails per batch
- Each email validated independently
- Failed emails don't affect successful ones

Use cases:
- Sending different transactional emails simultaneously
- Mixed email types in one API call
- High-volume transactional sending

Not for: Newsletter-style emails with same content → Use /api/bulk-send instead

### Send bulk emails (mail merge)

 - [POST /api/bulk-send](https://developers.mailerlogic.com/customer-api.openapi/email-sending/paths/~1api~1bulk-send/post.md): 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

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

## Profile

Manage your customer profile, view usage limits, and rotate API keys.
Start here to understand your account settings and available resources.


### Get customer profile

 - [GET /api/customer/profile](https://developers.mailerlogic.com/customer-api.openapi/profile/paths/~1api~1customer~1profile/get.md): Retrieve your account profile including:
- Current usage and remaining quota
- Domain limits and tracking settings
- API key (masked for security)

Use this to:
- Monitor monthly email usage
- Check available resources
- Verify account status

### Update customer profile

 - [PUT /api/customer/profile](https://developers.mailerlogic.com/customer-api.openapi/profile/paths/~1api~1customer~1profile/put.md): Update customer profile settings such as webhook URL.

### Rotate API key

 - [POST /api/customer/rotate-key](https://developers.mailerlogic.com/customer-api.openapi/profile/paths/~1api~1customer~1rotate-key/post.md): Generate a new API key for the customer account. The old key will be immediately invalidated.
Important: Update all applications with the new key immediately.

## SMTP

Get SMTP credentials for sending emails directly through our mail servers.
Use these endpoints to retrieve and rotate your SMTP passwords.


### Get SMTP credentials

 - [GET /api/smtp-credentials](https://developers.mailerlogic.com/customer-api.openapi/smtp/paths/~1api~1smtp-credentials/get.md): Retrieve your SMTP server credentials for sending emails.

Use these credentials to configure your email client, application, or mail library.
Port 587 (STARTTLS) is recommended for best compatibility.

### Rotate SMTP password

 - [POST /api/smtp-credentials/rotate](https://developers.mailerlogic.com/customer-api.openapi/smtp/paths/~1api~1smtp-credentials~1rotate/post.md): Generate a new SMTP password. The old password will be immediately invalidated.

## Domains

Add and verify sender domains for email authentication.
Configure SPF, DKIM, and DMARC records to improve deliverability.


### List all domains

 - [GET /api/customer/domains](https://developers.mailerlogic.com/customer-api.openapi/domains/paths/~1api~1customer~1domains/get.md): Retrieve all domains registered to your account with their verification status.
Use this to check which domains are ready for sending emails.

### Add domain

 - [POST /api/customer/domains](https://developers.mailerlogic.com/customer-api.openapi/domains/paths/~1api~1customer~1domains/post.md): Register a new domain for sending emails. This will generate DKIM keys and DNS records.
After adding, use the DNS endpoint to get records that need to be configured.

### Get required DNS records

 - [GET /api/customer/domains/{id}/dns](https://developers.mailerlogic.com/customer-api.openapi/domains/paths/~1api~1customer~1domains~1%7Bid%7D~1dns/get.md): Get the DNS records you need to configure for this domain.
Add these TXT records to your DNS provider to verify ownership and enable email authentication (SPF, DKIM, DMARC).

### Verify domain

 - [POST /api/customer/domains/{id}/verify](https://developers.mailerlogic.com/customer-api.openapi/domains/paths/~1api~1customer~1domains~1%7Bid%7D~1verify/post.md): Verify DNS records for the domain. This checks SPF, DKIM, DMARC, and domain verification records.

### Delete domain

 - [DELETE /api/customer/domains/{id}](https://developers.mailerlogic.com/customer-api.openapi/domains/paths/~1api~1customer~1domains~1%7Bid%7D/delete.md): Remove a domain from the account. This cannot be undone.

## Statistics

Access detailed email delivery and engagement metrics.
Query sends, bounces, opens, clicks, and spam complaints with flexible date filters.


### Get usage statistics

 - [GET /api/customer/usage](https://developers.mailerlogic.com/customer-api.openapi/statistics/paths/~1api~1customer~1usage/get.md): Retrieve current month's email usage and delivery statistics.

### Get outbound statistics overview

 - [GET /api/stats/outbound](https://developers.mailerlogic.com/customer-api.openapi/statistics/paths/~1api~1stats~1outbound/get.md): Overview of all outbound email statistics with optional date filtering.

### Get send statistics

 - [GET /api/stats/outbound/sends](https://developers.mailerlogic.com/customer-api.openapi/statistics/paths/~1api~1stats~1outbound~1sends/get.md): Daily breakdown of emails sent with optional filtering.

### Get bounce statistics

 - [GET /api/stats/outbound/bounces](https://developers.mailerlogic.com/customer-api.openapi/statistics/paths/~1api~1stats~1outbound~1bounces/get.md): Daily breakdown of bounced emails with hard/soft bounce classification.

### Get spam complaint statistics

 - [GET /api/stats/outbound/spam](https://developers.mailerlogic.com/customer-api.openapi/statistics/paths/~1api~1stats~1outbound~1spam/get.md): Daily breakdown of spam complaints.

### Get open statistics

 - [GET /api/stats/outbound/opens](https://developers.mailerlogic.com/customer-api.openapi/statistics/paths/~1api~1stats~1outbound~1opens/get.md): Daily breakdown of email opens (total and unique).

### Get platform statistics

 - [GET /api/stats/outbound/opens/platforms](https://developers.mailerlogic.com/customer-api.openapi/statistics/paths/~1api~1stats~1outbound~1opens~1platforms/get.md): Breakdown of email opens by email client platform (Gmail, Outlook, Apple Mail, etc.).

### Get click statistics

 - [GET /api/stats/outbound/clicks](https://developers.mailerlogic.com/customer-api.openapi/statistics/paths/~1api~1stats~1outbound~1clicks/get.md): Daily breakdown of link clicks (total and unique).

## Content Scoring

Analyze email content for spam patterns before sending.
Get actionable feedback to improve deliverability scores.


### Analyze email content

 - [POST /api/content-score](https://developers.mailerlogic.com/customer-api.openapi/content-scoring/paths/~1api~1content-score/post.md): Test your email content for spam triggers before sending.
Get a deliverability score (0-100, higher is better) with specific issues and suggestions for improvement.

Use this to:
- Check emails before sending campaigns
- Improve inbox placement rates
- Identify problematic content patterns

Rate Limit: Subject to monthly quota (default: 1000 checks/month)

## Events

Query granular email events and build custom analytics.
Enterprise feature - must be enabled on your account.


### Query email events

 - [GET /api/v1/events](https://developers.mailerlogic.com/customer-api.openapi/events/paths/~1api~1v1~1events/get.md): Query email events with advanced filtering.
Note: This is an enterprise feature that must be enabled on your account.
Requires enable_event_tracking and enable_event_api to be enabled.

### Get events for specific email

 - [GET /api/v1/emails/{email_id}/events](https://developers.mailerlogic.com/customer-api.openapi/events/paths/~1api~1v1~1emails~1%7Bemail_id%7D~1events/get.md): Retrieve all events for a specific email in chronological order.
Note: This is an enterprise feature that must be enabled on your account.

## Tracking

Public endpoints for open and click tracking.
These are called automatically by email clients - no authentication required.


### Track email open

 - [GET /track/o/{token}](https://developers.mailerlogic.com/customer-api.openapi/tracking/paths/~1track~1o~1%7Btoken%7D/get.md): Open tracking pixel endpoint. Returns a 1x1 transparent GIF.
This endpoint is embedded in emails and called when the email is opened.
Public endpoint - no authentication required.

### Track link click

 - [GET /track/c/{token}](https://developers.mailerlogic.com/customer-api.openapi/tracking/paths/~1track~1c~1%7Btoken%7D/get.md): Click tracking redirect endpoint. Logs the click and redirects to the original URL.
Public endpoint - no authentication required.

### Unsubscribe (manual)

 - [GET /track/u/{token}](https://developers.mailerlogic.com/customer-api.openapi/tracking/paths/~1track~1u~1%7Btoken%7D/get.md): Manual unsubscribe endpoint. Shows a confirmation page.
Public endpoint - no authentication required.

### One-click unsubscribe (RFC 8058)

 - [POST /track/u/{token}](https://developers.mailerlogic.com/customer-api.openapi/tracking/paths/~1track~1u~1%7Btoken%7D/post.md): One-click unsubscribe endpoint per RFC 8058.
Email clients can call this to instantly unsubscribe users.
Public endpoint - no authentication required.

## Webhooks

Receive real-time notifications for bounces and complaints.
Configure these endpoints in your mail server or monitoring tools.


### Receive bounce notifications

 - [POST /webhooks/bounce](https://developers.mailerlogic.com/customer-api.openapi/webhooks/paths/~1webhooks~1bounce/post.md): Webhook endpoint for receiving bounce notifications from mail servers or monitoring services.
Public endpoint - configure this URL in your mail server or monitoring service.

The system will process the bounce and update email status automatically.

### Receive spam complaint notifications

 - [POST /webhooks/complaint](https://developers.mailerlogic.com/customer-api.openapi/webhooks/paths/~1webhooks~1complaint/post.md): Webhook endpoint for receiving spam complaint notifications.
Public endpoint - configure this URL in your mail server or feedback loop service.