Eingehende Routen

Routen legen fest, wie MailLand eingehende E-Mails für eine Domain verarbeitet. Jede Route gleicht den lokalen Teil des Empfängers ab (der Teil der Adresse vor dem @) und führt eine oder mehrere Aktionen aus: speichern, an einen Webhook zustellen, weiterleiten, per SMTP ablehnen oder verwerfen. Routen werden in Prioritätsreihenfolge ausgewertet (niedrigste Zahl zuerst), und die erste übereinstimmende Route gewinnt.

ÜbereinstimmungstypenLink zum Abschnitt kopieren

Der Abgleich ist ohne Berücksichtigung von Groß-/Kleinschreibung und erfolgt immer gegen den lokalen Teil, [email protected] und [email protected] treffen beide auf eine Route mit Muster support zu, die auf dieselbe Domain beschränkt ist.

RoutenaktionenLink zum Abschnitt kopieren

Das Feld actions einer Route ist eine Liste aus einem oder mehreren der folgenden Werte:

store und webhook können miteinander und mit forward kombiniert werden. reject, drop und unsubscribe sind terminal: jede muss die einzige Aktion der Route sein; die API lehnt eine Anfrage ab, die eine dieser Aktionen mit einer anderen kombiniert.

WeiterleitungszieleLink zum Abschnitt kopieren

Bevor an eine Adresse weitergeleitet wird, muss deren Inhaber zustimmen: außer die Adresse liegt auf einer Ihrer eigenen, vollständig für den Versand verifizierten Domains. Für eine externe Adresse gibt es keinen Weg daran vorbei: Es schützt den Inhaber des Ziels davor, E-Mails zu erhalten, denen er nie zugestimmt hat, und schützt Ihre Versandreputation vor einer Adresse, die bounct oder sich beschwert.

Beim Erstellen oder Aktualisieren einer Route mit forward in actions erledigt MailLand automatisch:

1. Einen Weiterleitungsziel-Datensatz für forwardToEmail anlegen (oder wiederverwenden), pro Mandant: dieselbe Adresse wird über jede Route hinweg wiedererkannt, die an sie weiterleitet.
2. Falls die Adresse eine Bestätigung braucht und noch nie gefragt wurde, eine Bestätigungs-E-Mail mit einem Link senden.

Das Speichern der Route selbst gelingt immer; eine fehlgeschlagene Bestätigungs-E-Mail lässt die Route nicht scheitern: das Ziel bleibt einfach pending (nichts wird dorthin weitergeleitet), bis Sie die Bestätigung erneut anfordern.

BestätigungslinkLink zum Abschnitt kopieren

Der Link in der Bestätigungs-E-Mail ist 7 Tage gültig und einmal verwendbar: Sobald der Empfänger bestätigt oder ablehnt, zeigt ein erneuter Aufruf des Links nur dieselbe Entscheidung an, sie kann durch erneutes Aufrufen nicht rückgängig gemacht werden. Ein abgelaufener, nie entschiedener Link liefert bei erneutem Aufruf 410 Gone.

• Bestätigen: an diese Adresse wird künftig für diesen Mandanten weitergeleitet.
• Ablehnen: endgültig. Für diesen Mandanten wird nie wieder an die Adresse weitergeleitet, und der Mandant kann für sie keine erneute Bestätigung anfordern.

Ein Weiterleitungsziel abrufenLink zum Abschnitt kopieren

GET https://api.mail.land/v1/transactional/inbound/forward-destinations/{destinationId}

{
  "id": "f2k9m3q7p4w8x1",
  "email": "[email protected]",
  "status": "pending",
  "confirmedVia": null,
  "lastSentAt": "2026-09-26T10:00:00Z",
  "confirmedAt": null,
  "declinedAt": null
}

status ist einer von pending, confirmed oder declined. confirmedVia ist link, wenn der Inhaber über die E-Mail bestätigt hat, verified_domain, wenn die Adresse auf einer Ihrer eigenen, für den Versand verifizierten Domains liegt und keine Bestätigung brauchte, sonst null. Die Antwort einer Route trägt dasselbe Objekt unter forwardDestination (siehe die Routenantwort unten).

Eine Bestätigung erneut sendenLink zum Abschnitt kopieren

POST https://api.mail.land/v1/transactional/inbound/forward-destinations/{destinationId}/resend

Nur für ein Ziel, das noch pending ist und tatsächlich einen Link braucht (eine Adresse auf einer Ihrer eigenen verifizierten Versand-Domains liefert 409 FORWARD_DESTINATION_NO_CONFIRMATION_NEEDED, da es nichts erneut zu senden gibt). Ratenbegrenzt: höchstens einmal alle 5 Minuten und 5-mal pro Tag je Ziel, sowie 50-mal pro Tag für den gesamten Mandanten. Das Überschreiten eines der beiden Limits liefert 429 FORWARD_CONFIRMATION_RATE_LIMITED.

Route erstellenLink zum Abschnitt kopieren

Routen gehören zu einer Domain und werden unter dieser Domain erstellt.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes

{
  "name": "Support Inbox",
  "matchType": "exact",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "priority": 10
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Inbox",
    "matchType": "exact",
    "matchPattern": "support",
    "actions": ["store", "webhook"],
    "webhookId": "w4k8m2q7p9x3z1",
    "priority": 10
  }'

AntwortLink zum Abschnitt kopieren

{
  "id": "r7k3m9q2p4w8x1",
  "name": "Support Inbox",
  "domainId": "k3v9x2m8q1w7z4",
  "domainName": "yourdomain.com",
  "priority": 10,
  "isEnabled": true,
  "matchType": "Exact",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "webhookName": "Support Webhook",
  "webhookUrl": "https://yourapp.com/webhooks/support",
  "forwardToEmail": null,
  "forwardDestination": null,
  "rejectStatus": null,
  "rejectMessage": null,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Anfragen akzeptieren matchType in beliebiger Groß-/Kleinschreibung; Antworten geben immer den Enum-Namen mit großem Anfangsbuchstaben zurück: Exact, Prefix, Suffix, Contains, PlusAddressing, CatchAll, Regex. Vergleichen Sie den matchType einer Antwort nicht mit einer Kleinschreibungs-Zeichenkette.

forwardDestination ist nur gesetzt, wenn actions forward enthält; es trägt dasselbe Objekt wie unter Ein Weiterleitungsziel abrufen beschrieben:

{
  "...": "...",
  "actions": ["store", "forward"],
  "forwardToEmail": "[email protected]",
  "forwardDestination": {
    "id": "f2k9m3q7p4w8x1",
    "email": "[email protected]",
    "status": "pending",
    "confirmedVia": null,
    "lastSentAt": "2026-09-26T10:00:00Z",
    "confirmedAt": null,
    "declinedAt": null
  }
}

Routen einer Domain auflistenLink zum Abschnitt kopieren

GET https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes

Gibt alle Routen der Domain zurück, sortiert nach Priorität (niedrigste zuerst).

curl https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "items": [
    { "id": "r7k3m9q2p4w8x1", "name": "Support Inbox", "priority": 10, "isEnabled": true, "..." : "..." }
  ],
  "totalCount": 1
}

Alle Routen auflistenLink zum Abschnitt kopieren

Um Routen über alle Domains eines Tenants hinweg aufzulisten, verwenden Sie stattdessen den cursor-basierten Endpunkt:

GET https://api.mail.land/v1/transactional/inbound/routes

Routendetails abrufenLink zum Abschnitt kopieren

GET https://api.mail.land/v1/transactional/inbound/routes/{routeId}

curl https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Route aktualisierenLink zum Abschnitt kopieren

PUT https://api.mail.land/v1/transactional/inbound/routes/{routeId}

Der Anfragetext entspricht der Erstellungsanfrage, aber jedes Feld ist optional: es werden nur die gesendeten Felder aktualisiert.

curl -X PUT https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "matchPattern": "help",
    "priority": 5
  }'

Route umschaltenLink zum Abschnitt kopieren

Schaltet isEnabled um, ohne andere Felder zu berühren. Kein Anfragetext.

POST https://api.mail.land/v1/transactional/inbound/routes/{routeId}/toggle

curl -X POST https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1/toggle \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Routen neu ordnenLink zum Abschnitt kopieren

Aktualisieren Sie die Priorität aller Routen einer Domain auf einmal, indem Sie die Routen-IDs in der gewünschten Reihenfolge übergeben: die erste ID wird Priorität 1, die zweite Priorität 2 usw.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes/reorder

{
  "routeIds": ["r7k3m9q2p4w8x1", "m2p8w4x1k7q3z9", "x4k1p7m3q9w2z8"]
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes/reorder \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "routeIds": ["r7k3m9q2p4w8x1", "m2p8w4x1k7q3z9", "x4k1p7m3q9w2z8"]
  }'

Route testenLink zum Abschnitt kopieren

Prüfen Sie, welche Route auf eine bestimmte Empfängeradresse zutreffen würde, ohne eine E-Mail zu verarbeiten.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes/test

{
  "emailAddress": "[email protected]"
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "[email protected]"
  }'

{
  "matched": true,
  "matchedRouteId": "r7k3m9q2p4w8x1",
  "matchedRouteName": "Support Inbox",
  "actions": ["store", "webhook"]
}

Wenn keine Route zutrifft, ist die Antwort 200 mit matched: false, und matchedRouteId/matchedRouteName/actions sind alle null. 404 bedeutet, dass die Domain nicht gefunden wurde oder die getestete Adresse ungültig ist (kein @).

Route löschenLink zum Abschnitt kopieren

DELETE https://api.mail.land/v1/transactional/inbound/routes/{routeId}

curl -X DELETE https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

BeispielroutenLink zum Abschnitt kopieren

Catch-all-Route: jeden nicht zugeordneten Empfänger speichern:

{
  "name": "Catch All",
  "matchType": "catchall",
  "matchPattern": "*",
  "actions": ["store"],
  "priority": 999
}

Plus-Adressierung: alle Varianten von support+*@yourdomain.com an einen Webhook leiten:

{
  "name": "Support Tickets",
  "matchType": "plusaddressing",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "priority": 5
}

Ablehnung per SMTP: Mail an ein stillgelegtes Postfach ablehnen, bevor sie angenommen wird:

{
  "name": "Retired Mailbox",
  "matchType": "exact",
  "matchPattern": "old-team",
  "actions": ["reject"],
  "rejectStatus": "550 5.1.1",
  "rejectMessage": "Mailbox does not exist",
  "priority": 1
}

So sieht eine weitergeleitete Kopie ausLink zum Abschnitt kopieren

Eine weitergeleitete Kopie ist eine neue, gewöhnliche transaktionale E-Mail, kein rohes Relay der Original-Bytes, gesendet von Ihrer verifizierten Domain, damit sie DKIM und DMARC beim Postfach des Ziels besteht:

• From: "<Name des ursprünglichen Absenders> via <passende Adresse>@<Ihre Domain>", z. B. "Jane Doe via [email protected]". Ein Anzeigename, der wie eine Adresse aussieht (enthält @, < oder >), wird durch die reine Original-Adresse ersetzt, damit eine Kopie niemals eine Marke unter Ihrem DKIM vortäuschen kann.
• Reply-To: der Reply-To der Originalnachricht, falls vorhanden, sonst die Adresse des ursprünglichen Absenders, damit Antworten den echten Autor erreichen, nicht Sie.
• Kein Tracking: Öffnungs- und Klick-Tracking sind bei einer weitergeleiteten Kopie immer aus, unabhängig von den Tracking-Einstellungen Ihres Workspaces.
• Keine Branding-Fußzeile: die Fußzeile, die andere Sends im Free-Plan tragen können, wird nie hinzugefügt.
• Anhänge: gefiltert nach denselben Regeln wie ein ausgehender API-Versand (Typ, Anzahl, Gesamtgröße). Was weggelassen wird, steht als Hinweis am Anfang der Kopie: "Forwarded without N attachment(s) that exceed the outbound attachment limits: ...", die Kopie kommt trotzdem an, nur ohne diese Teile.
• Tag: jede weitergeleitete Kopie trägt das Tag inbound-forward, damit Sie sie in Ihrem normalen Nachrichtenprotokoll finden; ihr Zustellstatus (queued, sent, delivered, bounced usw.) ist derselbe Status, den jeder andere transaktionale Versand erhält, da sie dieselbe Zustellpipeline durchläuft.
• Nutzung: jede weitergeleitete Kopie zählt als ein Versand gegen das Kontingent und die Abrechnung Ihres Plans und erscheint als eigene Zeile "Inbound forward" in der Nutzungsübersicht, getrennt von API-, SMTP-, Kampagnen- und Automatisierungs-Sends.

Was nie weitergeleitet wirdLink zum Abschnitt kopieren

Eine Nachricht, die zu einer forward-Route passt, wird nicht weitergeleitet und nie abgerechnet, wenn:

• Sie als Spam markiert wurde oder der Absender als Spam blockiert ist.
• Sie DMARC nicht bestanden hat, gemessen an der effektiven Richtlinie der Absender-Domain, die quarantine oder reject ist, ermittelt, indem von der Absender-Domain aufwärts nach dem nächsten anwendbaren Eintrag gesucht wird, sodass das eigene sp= einer Subdomain deren organisatorischer p=-Richtlinie vorgeht und ein t=y- (Test-) oder pct=0-Eintrag eine Richtlinienstufe niedriger behandelt wird, eine Weiterleitung würde eine Nachricht erneut signieren, deren Absender die Empfänger ausdrücklich um Ablehnung gebeten hat.
• Sie oder ihr HTML-/Text-Body die ausgehenden Größenlimits der Plattform überschreitet.
• Eine Weiterleitung eine Schleife erzeugen würde: das Ziel ist einer der eigenen Empfänger der Nachricht, oder sie trägt bereits zu viele Hops oder Received-Header.

Eine Kopie, die zulässig ist, aber vorübergehend nicht gesendet werden kann (eine Richtlinienpause, ein Kontingentfenster, ein Ausfall), wird mit Backoff bis zu 24 Stunden wiederholt und läuft dann ab, ohne gesendet zu werden. Eine Route, die deaktiviert, gelöscht wird oder deren Ziel sich nach Empfang einer Nachricht ändert, stoppt auch jede noch wartende Kopie: die aktuelle Routenkonfiguration ist immer maßgeblich.

Das Ergebnis einer Weiterleitung prüfenLink zum Abschnitt kopieren

Jede eingehende E-Mail, die zu einer forward-Route passte, trägt ein forwards-Array in ihrer Detailantwort (GET /v1/transactional/inbound/emails/{id}): einen Eintrag pro Ziel, an das die Nachricht zur Weiterleitung eingereiht wurde, damit Sie sehen, was tatsächlich passiert ist, nicht nur, wohin sie konfiguriert war.

"forwards": [
  {
    "destination": "[email protected]",
    "status": "Admitted",
    "reason": null,
    "omittedAttachmentCount": 0,
    "messageId": "m_01hz3k...",
    "createdAt": "2026-09-26T10:00:00Z",
    "updatedAt": "2026-09-26T10:00:02Z"
  }
]

status ist einer von:

Pending, Processing und Deferred sind die einzigen nicht endgültigen Status, jeder andere Wert ist endgültig.

Fehlerantworten für WeiterleitungenLink zum Abschnitt kopieren

FehlerantwortenLink zum Abschnitt kopieren

Nächste SchritteLink zum Abschnitt kopieren

• Inbound Overview: wie die Verarbeitung eingehender E-Mails funktioniert
• Inbound Webhooks: Webhook-Payload-Format und Zustellung
• Domains: MX-Records für eingehende E-Mails konfigurieren