Skip to content

MailerLogic API (1.0.0)

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 X-API-Key header
  3. Start sending emails via SMTP or API

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

Download OpenAPI description
customer-api.openapi.json
customer-api.openapi.yaml
Overview
URL
https://support.mailerlogic.com
Support
support@mailerlogic.com
Languages
Servers
US Data Center
https://api.mailerlogic.net
EU Data Center (coming soon)
https://eu-api.mailerlogic.net

Quickstart Guide

Get started with MailerLogic in minutes. This guide walks you through sending your first email.

Features Overview

MailerLogic provides enterprise-grade email delivery infrastructure with powerful APIs, deliverability optimization, and comprehensive analytics. Built by developers, for developers.

Email Sending

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

Operations

Profile

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

Operations

SMTP

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

Operations

Sending Domains

Add and verify domains for sending authenticated emails. Configure SPF, DKIM, and DMARC records to improve deliverability.

Operations

Tracking Domains

Manage custom tracking domains for branded click and open tracking. Tracking domains allow you to use your own domain (e.g., track.yourdomain.com) instead of the default mailerlogic.net domain for tracking links and pixels.

Setup workflow:

  1. Create tracking domain
  2. Add CNAME record to DNS
  3. Verify DNS configuration
  4. SSL automatically provisions (1-2 minutes)
  5. Assign to sending domains
Operations

Statistics

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

Operations

Content Scoring

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

Operations

Email Validation

Enterprise email validation API to reduce bounce rates and protect sender reputation. Real-time validation with syntax checking, domain verification, comprehensive disposable email detection, and MX record validation. Built-in intelligence to identify role accounts and suggest corrections for common typos.

Operations

Risk Assessment

Pre-send risk assessment API for Professional and Enterprise plans. Preview risk scores before sending emails to reduce bounce rates, improve deliverability, and maintain sender reputation. Get detailed risk analysis with actionable recommendations and enforcement policy insights.

Operations

Events

🔒 Enterprise Feature - Query email lifecycle events with human engagement detection and device analytics.

Operations

Suppressions

Manage system-level suppressions for bounces and spam complaints.

Suppression Types:

  • Hard Bounces: Permanent delivery failures (automatically added by the system)
  • Soft Bounces: Temporary delivery failures (automatically added after threshold)
  • Complaints: Spam complaints and feedback loop reports

Suppression Scope:

  • Global: Applies to ALL your domains (when no domain_id specified)
  • Domain-specific: Applies to a specific domain only

Key Features:

  • Automatic bounce and complaint handling
  • Whitelist management to override suppressions
  • List all suppressions with filtering
  • Manual suppression management

Automated list hygiene to protect your sender reputation and ensure compliance.

Operations

Unsubscribes

Manage user consent and opt-out preferences.

User-Initiated Opt-Outs:

  • Unsubscribe link clicks in emails
  • API-based unsubscribe requests
  • Domain-specific or global unsubscribe preferences

Unsubscribe Scope:

  • Global: User opts out from ALL your domains
  • Domain-specific: User opts out from a specific domain only

Key Features:

  • Add emails to unsubscribe list
  • Remove (re-subscribe) emails
  • List all unsubscribed emails with filtering
  • Automatic enforcement during email sending

Ensures compliance with CAN-SPAM, GDPR, and other anti-spam regulations.

Operations

Health Score

Monitor your account's email health and engagement quality metrics. Get a 0-100 score with reputation grade (A+ to F) and actionable insights.

Operations

Tracking

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

Operations

Outbound Webhooks

MailerLogic sends real-time webhook notifications to your configured endpoint for all email events.

Webhook Scopes:

Customer-Level Webhooks (domain_ids = null or [])

  • Receives events from ALL domains
  • Simplest setup for single-backend applications

Single Domain Webhooks (domain_ids = [uuid])

  • Receives events from ONE specific domain
  • Useful for isolated domains

Domain Group Webhooks (domain_ids = [uuid1, uuid2, ...])

  • Receives events from MULTIPLE specific domains
  • Perfect for grouping related domains when webhook endpoint limits apply
  • Example: Plan has 20 domains, 5 webhook limit → group marketing domains, support domains, etc.

Mixed Approach

  • You can combine all three types
  • Domain-specific/group webhooks fire first, then customer-level
  • Maximize efficiency with limited webhook endpoints

Create customer-level webhook (all domains):

curl -X POST https://api.mailerlogic.net/api/v1/customer/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/mailerlogic",
    "events": ["email.delivered", "email.opened", "email.clicked", "email.bounced", "email.complained"],
    "name": "Production Webhook",
    "domain_ids": null,
    "is_active": true
  }'

Create domain group webhook (multiple domains):

curl -X POST https://api.mailerlogic.net/api/v1/customer/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://marketing.example.com/webhook",
    "events": ["email.opened", "email.clicked"],
    "name": "Marketing Domains Group",
    "domain_ids": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002",
      "550e8400-e29b-41d4-a716-446655440003"
    ],
    "is_active": true
  }'

Create single domain webhook:

curl -X POST https://api.mailerlogic.net/api/v1/customer/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://support.example.com/webhook",
    "events": ["email.delivered", "email.bounced"],
    "name": "Support Domain Only",
    "domain_ids": ["550e8400-e29b-41d4-a716-446655440000"],
    "is_active": true
  }'

All webhook events include:

  • event - Event type (e.g., "email.delivered", "email.opened")
  • timestamp - ISO 8601 timestamp
  • email_id - UUID of the email (except unsubscribe events)
  • tag - Optional tag for filtering/grouping (if provided when sending)
  • metadata - Optional custom metadata object (if provided when sending)

Events sent to your endpoint:

Operations

email.failed

Sent when email fails to send.

{
  "event": "email.failed",
  "timestamp": "2025-12-27T12:34:57.345Z",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "recipient": "blocked@example.com",
  "reason": "Blocked by content filter",
  "error": "Content violated filtering rules",
  "tag": "campaign-welcome",
  "metadata": {
    "campaign_id": "welcome-2025",
    "customer_segment": "new-users"
  }
}

Note: tag and metadata fields are included if provided when sending the email.

Webhook Best Practices:

  1. Respond quickly - Return 200 OK within 5 seconds
  2. Process asynchronously - Queue webhook for processing, respond immediately
  3. Handle retries - Webhooks retry 5 times with exponential backoff if your endpoint fails
  4. Validate payloads - Check the event field and validate structure
  5. Use HTTPS - Always use HTTPS endpoints for security

Testing Webhooks:

Use ngrok or webhook.site to test locally:

ngrok http 3000
# Create webhook with ngrok URL
curl -X POST https://api.mailerlogic.net/api/v1/customer/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"url": "https://abc123.ngrok.io/webhooks", "events": ["delivered"]}'

# Send a test webhook
curl -X POST https://api.mailerlogic.net/api/v1/customer/webhooks/{WEBHOOK_ID}/test \
  -H "X-API-Key: YOUR_API_KEY"

Webhook Delivery:

  • Delivery timeout: 30 seconds
  • Retry attempts: 5 (with exponential backoff)
  • Retry schedule: 1s, 5s, 30s, 2m, 10m

See the complete integration guide at https://docs.mailerlogic.com/webhooks

List webhook endpoints

Request

Retrieve all configured webhook endpoints for your account.

Tier Limits:

  • Starter: 1 webhook endpoint
  • Professional: 3 webhook endpoints
  • Business: 10 webhook endpoints
  • Custom: Configurable limit
Security
ApiKeyAuth
curl -i -X GET \
  https://api.mailerlogic.net/api/v1/customer/webhooks \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Webhooks retrieved successfully

Bodyapplication/json
webhooksArray of objects(WebhookEndpoint)
limitinteger

Maximum webhook endpoints allowed

Example: 10
usedinteger

Number of webhooks currently configured

Example: 3
Response
application/json
{
  "webhooks": [
    { … }
  ],
  "limit": 10,
  "used": 3
}

Create webhook endpoint

Request

Create a new webhook endpoint to receive real-time email event notifications.

Webhook Scopes:

  • Customer-Level (domain_ids = null/empty): Receives events from ALL domains
  • Single Domain (domain_ids = [uuid]): Receives events from ONE domain
  • Domain Group (domain_ids = [uuid1, uuid2, ...]): Receives events from MULTIPLE domains

Use Case - Plan Limits: If your plan has 20 domains but only 5 webhook endpoints, group domains:

  • Webhook 1: [marketing-domain, campaigns-domain, newsletters-domain] → marketing app
  • Webhook 2: [support-domain, tickets-domain] → support app
  • Webhook 3: [] (all remaining domains) → main backend

Event Types:

  • email.sent - Email accepted for delivery
  • email.delivered - Successfully delivered to recipient
  • email.opened - Recipient opened the email
  • email.clicked - Recipient clicked a link
  • email.bounced - Email bounced
  • email.complained - Spam complaint received
  • email.unsubscribed - Recipient unsubscribed
  • email.failed - Delivery failed

Examples:

Customer-level webhook (all domains):

{
  "url": "https://api.example.com/webhook",
  "events": ["email.delivered", "email.bounced"],
  "domain_ids": null
}

Domain group webhook (multiple domains):

{
  "url": "https://marketing.example.com/webhook",
  "events": ["email.opened", "email.clicked"],
  "domain_ids": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002",
    "550e8400-e29b-41d4-a716-446655440003"
  ]
}

Single domain webhook (backward compatible):

{
  "url": "https://support.example.com/webhook",
  "events": ["email.delivered"],
  "domain_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}
Security
ApiKeyAuth
Bodyapplication/jsonrequired
namestring

Optional webhook identifier

Example: "Production Webhook"
urlstring(uri)required

HTTPS URL for webhook delivery

Example: "https://api.example.com/webhooks/email-events"
descriptionstring

Optional notes about this webhook

Example: "Main production webhook for email events"
domain_idsArray of strings or null(uuid)

Optional array of domain UUIDs to scope webhook to specific domains.

  • If null or empty array: webhook receives events from ALL domains (customer-level)
  • If array with 1 UUID: webhook receives events from ONE domain
  • If array with multiple UUIDs: webhook receives events from those specific domains (domain group)

Use Case: If your plan has 20 domains but only 5 webhook endpoints, group related domains together.

Example: ["550e8400-e29b-41d4-a716-446655440001","550e8400-e29b-41d4-a716-446655440002"]
eventsArray of stringsrequired

Event types to receive

Items Enum"email.sent""email.delivered""email.opened""email.clicked""email.bounced""email.complained""email.unsubscribed""email.failed"
Example: ["email.delivered","email.opened","email.clicked","email.bounced"]
is_activeboolean

Enable/disable webhook

Default true
domain_idstring or null(uuid)Deprecated

DEPRECATED: Use domain_ids array instead. For backward compatibility, this is converted to domain_ids: [domain_id].

Example: "550e8400-e29b-41d4-a716-446655440000"
curl -i -X POST \
  https://api.mailerlogic.net/api/v1/customer/webhooks \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "name": "Production Webhook",
    "url": "https://api.example.com/webhooks/email-events",
    "description": "Main production webhook for email events",
    "domain_ids": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002"
    ],
    "domain_id": "550e8400-e29b-41d4-a716-446655440000",
    "events": [
      "email.delivered",
      "email.opened",
      "email.clicked",
      "email.bounced"
    ],
    "is_active": true
  }'

Responses

Webhook created successfully.

⚠️ IMPORTANT: The response includes a secret field inside the webhook object. This is the ONLY time you'll see it - save it immediately!

Bodyapplication/json
webhookobject(WebhookEndpointWithSecret)

Webhook endpoint response that includes the signing secret. IMPORTANT: The secret is only returned when creating or regenerating. Save it securely - you won't see it again!

messagestring
Example: "Webhook created successfully"
Response
application/json
{
  "webhook": {
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Webhook",
    "url": "https://api.example.com/webhooks/email-events",
    "description": "Main production webhook",
    "domain_ids": [ … ],
    "domains": [ … ],
    "events": [ … ],
    "is_active": true,
    "secret": "whsec_8jKp3nXw7rQ9sL2mY4hT6vB1nC5xZ0aE7fG2hI9jK4lM6nO8pQ1rS3tU5vW7xY",
    "last_triggered_at": null,
    "last_status": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "message": "Webhook created successfully"
}