E-Mail-Protokolle

Suchen, filtern und inspizieren Sie detaillierte Zustellprotokolle für jede über Mail.Land gesendete E-Mail

Diese Seite listet nur transaktionale Nachrichten auf: Kampagnen- und Automatisierungs-E-Mails (einschließlich sys_*-Systemnachrichten) sind ausgeschlossen. Verwenden Sie den Endpunkt für Kampagnenempfänger (siehe Kampagnen) für den Marketing-/Automatisierungs-Sendeverlauf.

E-Mails auflisten

GET https://api.mail.land/v1/transactional/logs

List emails

curl "https://api.mail.land/v1/transactional/logs?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Abfrageparameter

Parameter	Typ	Standard	Beschreibung
`cursor`	string	-	Opaker Cursor aus dem `nextCursor` der vorherigen Seite. Für die erste Seite weglassen. Ein fehlerhafter oder manipulierter Cursor führt zu `400 INVALID_CURSOR`.
`limit`	int	20	Elemente pro Seite
`status`	string	-	Nach Status filtern (siehe unten)
`search`	string	-	Nach Empfänger, Betreff oder Nachrichten-ID suchen
`from`	datetime	Vor 30 Tagen	Startdatum
`to`	datetime	Jetzt	Enddatum
`refresh`	bool	false	Eine veraltete Seite vermeiden: es gibt keinen Zählungs-Cache mehr, der umgangen werden müsste

Statusfilter

Wert	Entspricht
`queued`	Wartet in der Warteschlange
`sent`	Vom MTA akzeptiert
`deferred` oder `retrying`	Vorübergehend verzögert
`delivered`	Erfolgreich zugestellt
`bounced`	Dauerhafter Bounce
`failed`	Systemfehler oder Admin-Bounce
`opened`	Empfänger hat die E-Mail geöffnet
`clicked`	Empfänger hat auf einen Link geklickt
`complained`	Empfänger hat eine Spam-Beschwerde eingereicht

Email logs response

{
  "items": [
    {
      "messageId": "t_a1b2c3d4e5f6",
      "recipient": "[email protected]",
      "subject": "Your order has shipped",
      "status": "delivered",
      "sentAt": "2026-02-17T12:34:56Z",
      "deliveredAt": "2026-02-17T12:34:58Z",
      "openedAt": "2026-02-17T13:15:00Z",
      "clickedAt": null,
      "bounceReason": null,
      "openCount": 2,
      "clickCount": 0
    },
    {
      "messageId": "t_d4e5f6a1b2c3",
      "recipient": "[email protected]",
      "subject": "Invoice #1234",
      "status": "bounced",
      "sentAt": "2026-02-17T12:30:00Z",
      "deliveredAt": null,
      "openedAt": null,
      "clickedAt": null,
      "bounceReason": "550 5.1.1 Mailbox not found",
      "openCount": 0,
      "clickCount": 0
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Statusprioritäten

Das Feld status spiegelt das Ereignis mit der höchsten Priorität für jede E-Mail wider:

complained (höchste)
clicked
opened
Zustellungsstatus: queued → sent → deferred → delivered → bounced → failed

Wurde eine E-Mail beispielsweise zugestellt und dann geöffnet, zeigt der Status opened.

Aus Leistungsgründen wird standardmäßig ein 30-tägiger Datumsbereich angewendet. Der Suchparameter filtert nach Empfänger-E-Mail, Betreffzeile oder Nachrichten-ID (Groß-/Kleinschreibung wird nicht berücksichtigt).

Protokollstatistiken

Aggregierte Statistiken für Ihre E-Mail-Protokolle abrufen:

GET https://api.mail.land/v1/transactional/logs/stats

Get log stats

curl "https://api.mail.land/v1/transactional/logs/stats" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parameter	Typ	Standard	Beschreibung
`from`	datetime	Vor 7 Tagen	Startdatum
`to`	datetime	Jetzt	Enddatum
`emailType`	int	-	`0` = Transaktional, `1` = Marketing. Weglassen deckt alle E-Mail-Typen ab: anders als "E-Mails auflisten" oben, das nur Transaktional zeigt.
`refresh`	bool	false	Cache umgehen

Log stats response

{
  "total": 4750,
  "accepted": 4750,
  "sent": 4700,
  "delivered": 4680,
  "opened": 1498,
  "clicked": 195,
  "bounced": 38,
  "complained": 1,
  "failed": 12,
  "queued": 20,
  "deliveryRate": 99.57,
  "openRate": 32.01,
  "clickRate": 13.02,
  "bounceRate": 0.81,
  "complaintRate": 0.021,
  "source": "clickhouse",
  "queryTimeMs": 32
}

Ratenberechnungen:

Rate	Formel
`deliveryRate`	`delivered / sent * 100`
`openRate`	`opened / delivered * 100`
`clickRate`	`clicked / delivered * 100`
`bounceRate`	`bounced / sent * 100`
`complaintRate`	`complained / sent * 100` (3 Dezimalstellen)

Antwortheader zeigen den Cache-Status an:

Header	Werte
`X-Cache`	`HIT`, `MISS` oder `FRESH`
`X-Stats-Source`	`cache` oder `clickhouse`
`Cache-Control`	Immer `no-store, no-cache, must-revalidate`

E-Mail-Detail

Vollständige Details für eine bestimmte E-Mail einschließlich der Ereignis-Zeitachse abrufen:

GET https://api.mail.land/v1/transactional/logs/{messageId}

Get email detail

curl https://api.mail.land/v1/transactional/logs/t_a1b2c3d4e5f6 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Email detail response

{
  "messageId": "t_a1b2c3d4e5f6",
  "recipient": "[email protected]",
  "fromEmail": "[email protected]",
  "subject": "Your order has shipped",
  "status": "opened",
  "sentAt": "2026-02-17T12:34:56Z",
  "deliveredAt": "2026-02-17T12:34:58Z",
  "openedAt": "2026-02-17T13:15:00Z",
  "clickedAt": null,
  "createdAt": "2026-02-17T12:34:55Z",
  "bounceReason": null,
  "bounceCategory": null,
  "ipAddress": null,
  "retryCount": 0,
  "smtpResponse": "250 2.0.0 OK",
  "openCount": 2,
  "clickCount": 0,
  "htmlContent": "<html>...</html>",
  "textContent": "Your order has shipped...",
  "events": [
    {
      "eventType": "delivered",
      "timestamp": "2026-02-17T12:34:58Z",
      "ipAddress": null,
      "userAgent": null,
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": "250 2.0.0 OK",
      "deviceType": null,
      "browser": null,
      "country": null,
      "city": null
    },
    {
      "eventType": "opened",
      "timestamp": "2026-02-17T13:15:00Z",
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": null,
      "deviceType": "desktop",
      "browser": "Chrome",
      "country": "US",
      "city": "San Francisco"
    },
    {
      "eventType": "opened",
      "timestamp": "2026-02-17T14:30:00Z",
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": null,
      "deviceType": "mobile",
      "browser": "Safari",
      "country": "US",
      "city": "San Francisco"
    }
  ]
}

Das Array events stammt aus ClickHouse und ist nach Zeitstempel sortiert. Falls ClickHouse vorübergehend nicht verfügbar ist, werden die E-Mail-Details trotzdem aus PostgreSQL zurückgegeben, aber events ist ein leeres Array.

Ereignisfelder

Feld	Beschreibung
`eventType`	`delivered`, `opened`, `clicked`, `bounced`, `complained`, sowie `accepted`, `sent`, `deferred`, `admin_bounce`, `oob_bounce`, `expired`
`timestamp`	Zeitpunkt des Ereignisses (UTC)
`ipAddress`	Client-IP (für Öffnungen/Klicks)
`userAgent`	Client-User-Agent-Zeichenfolge
`linkUrl`	Geklickte URL (für `clicked`-Ereignisse)
`bounceType`	`hard`, `soft` oder `unknown` (für `bounced`-Ereignisse)
`bounceReason`	SMTP-Antwort (für `bounced`-Ereignisse)
`smtpResponse`	Remote-Server-Antwort (für `delivered`-Ereignisse)
`deviceType`	`desktop`, `mobile` oder `tablet`
`browser`	Browsername (Chrome, Safari, Firefox usw.)
`country`	ISO-Ländercode
`city`	Stadtname

Fehlgeschlagene E-Mail erneut senden

Zustellung einer zurückgesendeten oder fehlgeschlagenen E-Mail erneut versuchen:

POST https://api.mail.land/v1/transactional/logs/{messageId}/retry

Retry failed email

curl -X POST https://api.mail.land/v1/transactional/logs/t_a1b2c3d4e5f6/retry \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Die Nachricht muss den Status Bounced oder Failed haben, und der Empfänger darf nicht unterdrückt sein.

Status	Code	Beschreibung
`200`	-	Wiederholung akzeptiert
`400`	`INVALID_REQUEST`	E-Mail ist nicht zurückgesendet oder fehlgeschlagen
`400`	`RECIPIENT_SUPPRESSED`	Empfänger befindet sich auf der Unterdrückungsliste
`404`	`RESOURCE_NOT_FOUND`	Nachricht nicht gefunden: nicht `EMAIL_NOT_FOUND`
`422`	`DOMAIN_NOT_VERIFIED`	Die sendende Domain ist nicht mehr verifiziert
`429`	`MARKETING_PAUSED`	Der Marketingversand ist für diesen Workspace derzeit pausiert
`422`	`RETRY_ATTACHMENTS_UNAVAILABLE`	Die Nachricht hatte Anhänge, die nicht mehr wiederhergestellt werden können; senden Sie sie stattdessen erneut mit den Anhängen
`422`	`RETRY_ATTACHMENTS_UNKNOWN`	Die Nachricht wurde gesendet, bevor Anhänge erfasst wurden, daher kann ein Retry die Anhänge nicht garantieren; senden Sie sie stattdessen erneut
`429`	`PLATFORM_CAPACITY_PROTECTION`	Neuer Versand ist kurz pausiert, um die Plattformkapazität zu schützen; nichts wurde geändert, versuchen Sie es gleich erneut
`503`	`RETRY_ATTACHMENT_STORAGE_UNAVAILABLE`	Die Anhänge konnten gerade nicht gelesen werden; nichts wurde geändert, versuchen Sie es gleich erneut

Die Wiederholung erstellt einen neuen E-Mail-Job mit dem ursprünglichen Inhalt und stellt ihn zur Zustellung in die Warteschlange. Wiederholte Kopien werden ohne Öffnungs-/Klick-Tracking versendet.

Nächste Schritte

Analytics – Übersicht: aggregierte Ereigniszusammenfassungen und Raten
Erweiterte Analytics: geografische, Geräte- und Tageszeit-Aufschlüsselungen
Bounces: Bounce-Behandlung und Wiederholungsversuche verstehen

E-Mail-Protokolle

E-Mails auflistenLink zum Abschnitt kopieren

AbfrageparameterLink zum Abschnitt kopieren

StatusfilterLink zum Abschnitt kopieren

StatusprioritätenLink zum Abschnitt kopieren

ProtokollstatistikenLink zum Abschnitt kopieren

E-Mail-DetailLink zum Abschnitt kopieren

EreignisfelderLink zum Abschnitt kopieren

Fehlgeschlagene E-Mail erneut sendenLink zum Abschnitt kopieren

Nächste SchritteLink zum Abschnitt kopieren

Auf dieser Seite