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_id - Stable event identifier. Store this value and ignore a delivery you have already processed; webhook delivery is at-least-once.
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

contact.confirmed

Sent when a double opt-in contact confirms their subscription and moves from pending_confirmation to subscribed.

{
  "event": "contact.confirmed",
  "timestamp": "2026-07-06T14:24:18.321Z",
  "data": {
    "contact_id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "subscriber@example.com",
    "previous_status": "pending_confirmation",
    "status": "subscribed",
    "confirmed_at": "2026-07-06T14:24:18.321Z",
    "source": "newsletter",
    "consent": {
      "source_url": "https://example.com/newsletter",
      "consent_text": "I agree to receive newsletters.",
      "timestamp": "2026-07-06T14:20:15Z"
    }
  }
}