Webhooks – Übersicht

Webhooks senden Ihrem Server HTTP-Benachrichtigungen in Echtzeit, wenn E-Mail-Ereignisse eintreten, Zustellungen, Bounces, Beschwerden und mehr. Anstatt den Status periodisch abzufragen, überträgt MailLand Ereignisse sofort bei ihrem Eintreten an Ihren Endpoint.

Funktionsweise von WebhooksLink zum Abschnitt kopieren

Einen Webhook erstellenLink zum Abschnitt kopieren

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

AnforderungsfelderLink zum Abschnitt kopieren

AntwortLink zum Abschnitt kopieren

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

Webhooks auflistenLink zum Abschnitt kopieren

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

Gibt bis zu 100 Webhooks sortiert nach Erstellungsdatum zurück (neueste zuerst).

Webhook-Details abrufenLink zum Abschnitt kopieren

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

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

Gibt die vollständige Webhook-Konfiguration sowie die 50 neuesten Zustellungsprotokolle zurück. Einzelheiten zu Zustellungsprotokollen finden Sie unter Retry-Logik.

Einen Webhook aktualisierenLink zum Abschnitt kopieren

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

Alle Felder sind optional: geben Sie nur die Felder an, die Sie ändern möchten.

Einen Webhook testenLink zum Abschnitt kopieren

Senden Sie ein Testereignis, um zu überprüfen, ob Ihr Endpoint funktioniert:

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
}

Der Testversand nutzt dieselbe Signierung und denselben Zustellweg wie ein echtes Ereignis. Ein Erfolg beweist daher Ihre URL, Ihr TLS und Ihre Signaturprüfung.

Er beweist nicht Ihr Abonnement: Ein Test wird auf Anforderung gesendet und nicht über Ihre Ereignisauswahl geroutet. Die letzten vier Felder beantworten das getrennt:

Ein "success": true zusammen mit "wouldReceiveRealEvents": false ist der wichtige Fall: Der Endpoint funktioniert, hat aber nichts abonniert, was zugestellt werden kann.

Schlägt der Test fehl, gibt das Feld errorType den Grund an: ssrf_blocked (die URL oder eine Weiterleitung von ihr zeigte auf ein Ziel, an das die Plattform nicht sendet) oder network_error (Timeout, TLS-Fehler, Verbindung abgelehnt; errorMessage enthält die Details).

Secret neu generierenLink zum Abschnitt kopieren

Falls Sie Ihr Webhook-Secret verloren haben oder es rotieren müssen:

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-BereichLink zum Abschnitt kopieren

Standardmäßig empfangen Webhooks Ereignisse für alle Domains in Ihrem Workspace. Um einen Webhook auf bestimmte Domains zu beschränken:

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

Nur Ereignisse, die sich auf diese Domains beziehen, lösen den Webhook aus.

Automatische Pausierung bei FehlernLink zum Abschnitt kopieren

MailLand pausiert Webhooks automatisch nach 10 aufeinanderfolgenden Zustellungsfehlern (pro Webhook über pauseThreshold konfigurierbar). Dies verhindert die Verschwendung von Ressourcen bei ausgefallenen Endpoints.

Wenn ein Webhook pausiert wird:

• Der Zeitstempel pausedAt wird gesetzt
• pausedReason beschreibt den Grund der Pausierung
• Ein account.webhook_paused-Ereignis wird an Ihre anderen aktiven Webhooks gesendet
• Eine In-App-Benachrichtigung wird erstellt

Einen pausierten Webhook fortsetzenLink zum Abschnitt kopieren

Nehmen Sie nach der Behebung des Problems die Zustellung wieder auf:

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

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

Diese Aktion löscht den Pausierungsstatus, setzt den Zähler für aufeinanderfolgende Fehler zurück und reaktiviert den Webhook (isActive wird wieder true), sodass zukünftige Ereignisse wieder normal zugestellt werden.

Einen Webhook löschenLink zum Abschnitt kopieren

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

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

Gibt 204 No Content zurück. Wenn der Webhook von eingehenden E-Mail-Routen verwendet wird, werden diese Routen automatisch aktualisiert oder deaktiviert.

FehlerantwortenLink zum Abschnitt kopieren

Nächste SchritteLink zum Abschnitt kopieren

• Ereignisse: vollständige Referenz aller Ereignistypen und Payloads
• Signaturverifizierung: Webhook-Authentizität überprüfen
• Retry-Logik: Wiederholungsverhalten und Fehlerbehandlung verstehen