Webhooks Overview

Webhooks deliver real-time HTTP notifications to your server when email events occur, deliveries, bounces, complaints, and more. Instead of polling for status changes, MailLand pushes events to your endpoint as they happen.

How Webhooks WorkCopy Anchor Link

Create a WebhookCopy Anchor Link

POST https://api.mail.land/v1/webhooks

curl -X POST https://api.mail.land/v1/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "includeFutureEvents": true,
    "scope": "all_domains"
  }'

Request FieldsCopy Anchor Link

ResponseCopy Anchor Link

Status: 201 Created

{
  "webhook": {
    "id": "k3m9x2p7qw4rtz",
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "includeFutureEvents": true,
    "scope": "all_domains",
    "domainIds": [],
    "isActive": true,
    "createdAt": "2026-02-17T10:00:00Z",
    "successCount": 0,
    "failureCount": 0,
    "consecutiveFailures": 0,
    "pauseThreshold": 10
  },
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0..."
}

List WebhooksCopy Anchor Link

GET https://api.mail.land/v1/webhooks

curl -X GET https://api.mail.land/v1/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

[
  {
    "id": "k3m9x2p7qw4rtz",
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced"],
    "isActive": true,
    "lastTriggeredAt": "2026-02-17T12:30:00Z",
    "lastSuccessAt": "2026-02-17T12:30:00Z",
    "successCount": 1542,
    "failureCount": 3,
    "consecutiveFailures": 0,
    "createdAt": "2026-02-10T08:00:00Z"
  }
]

Returns up to 100 webhooks ordered by creation date (newest first).

Get Webhook DetailCopy Anchor Link

GET https://api.mail.land/v1/webhooks/{id}

curl -X GET https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Returns the full webhook configuration plus the 50 most recent delivery logs. See Retry Logic for delivery log details.

Update a WebhookCopy Anchor Link

PUT https://api.mail.land/v1/webhooks/{id}

curl -X PUT https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "All Events",
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "isActive": true
  }'

All fields are optional: only include the fields you want to change.

Test a WebhookCopy Anchor Link

Send a test event to verify your endpoint is working:

POST https://api.mail.land/v1/webhooks/{id}/test

curl -X POST https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "success": true,
  "statusCode": 200,
  "statusText": "OK",
  "durationMs": 145,
  "responseBody": "{\"received\": true}",
  "headersSent": {
    "X-MLND-Signature": "t=1708171200,v1=abc123...",
    "X-MLND-Event-Id": "evt_test_abc123",
    "X-MLND-Event-Version": "1",
    "X-MLND-Event": "webhook.test",
    "X-MLND-Webhook-Id": "k3m9x2p7qw4rtz",
    "X-MLND-Attempt": "1"
  },
  "wouldReceiveRealEvents": true,
  "liveEvents": ["message.delivered", "message.bounced"],
  "dormantEvents": {},
  "subscriptionWarning": null
}

The test send uses the same signing and the same delivery transport as a real event, so a success here proves your URL, your TLS and your signature verification.

It does not prove your subscription: a test is sent on demand, not routed by your event selection. The last four fields answer that separately:

A "success": true alongside "wouldReceiveRealEvents": false is the important case: the endpoint works and is subscribed to nothing that can be delivered.

If the test fails, the errorType field indicates the reason: ssrf_blocked (the URL, or a redirect from it, pointed somewhere the platform refuses to send to) or network_error (timeout, TLS failure, connection refused, errorMessage carries the detail).

Regenerate SecretCopy Anchor Link

If you lose or need to rotate your webhook secret:

POST https://api.mail.land/v1/webhooks/{id}/regenerate-secret

curl -X POST https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz/regenerate-secret \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "secretKey": "whsec_x9y8z7w6v5u4..."
}

Domain ScopeCopy Anchor Link

By default, webhooks receive events for all domains in your workspace. To limit a webhook to specific domains:

{
  "webhookUrl": "https://your-app.com/webhooks/mailland",
  "scope": "selected_domains",
  "domainIds": ["d4n8q1zt5wm3xc", "b7r2mv9k0jy4pw"]
}

Only events related to those domains will trigger the webhook.

Auto-Pause on FailuresCopy Anchor Link

MailLand automatically pauses webhooks after 10 consecutive failed delivery attempts. This prevents wasting resources on endpoints that are down. The counter is of attempts, not of events, one event that exhausts its retry ladder contributes several failures, and any successful delivery resets it to zero.

When a webhook is paused:

• isActive becomes false
• The pausedAt timestamp is set
• The pausedReason describes why: the failure count and the last error
• An in-app notification is created

Resume a Paused WebhookCopy Anchor Link

After fixing the issue, resume delivery:

POST https://api.mail.land/v1/webhooks/{id}/resume

curl -X POST https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz/resume \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

This clears the pause state, resets the consecutive failure counter, and reactivates the webhook (isActive becomes true again), so future events are delivered to it normally.

Delete a WebhookCopy Anchor Link

DELETE https://api.mail.land/v1/webhooks/{id}

curl -X DELETE https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Returns 204 No Content. If the webhook is used by inbound email routes, those routes will be updated or disabled automatically.

Error ResponsesCopy Anchor Link

Next StepsCopy Anchor Link

• Events: complete reference of all event types and payloads
• Signature Verification: verify webhook authenticity
• Retry Logic: understand retry behavior and failure handling