API-Schlüssel

API-Schlüssel (Credentials) authentifizieren Ihre Anwendung gegenüber der MailLand-API. Jeder Schlüssel ist nach Produkt, Modus, Stream, Kanal und optional nach Domain und IP-Adresse eingeschränkt.

Im Dashboard erstellen und verwalten Sie Schlüssel unter Credentials in der Seitenleiste (Bereich Global). Dieselben Vorgänge stehen über die unten beschriebene API /v1/credentials zur Verfügung.

Die Authorization: Bearer-Beispiele auf dieser Seite verwenden das JWT-Zugriffstoken aus POST /v1/auth/login (siehe Login). API-Schlüssel sind anders: Senden Sie sie im Header X-API-Key, nie als Bearer-Token.

SchlüsselformatLink zum Abschnitt kopieren

Alle MailLand-API-Schlüssel folgen diesem Format:

ml_{mode}{product}{stream?}_{random45chars}

• ml_: Präfix für alle Schlüssel
• Modus: p (Produktion) oder s (Sandbox)
• Produkt: e (Senden), i (Eingehend), v (Validierung)
• Stream (nur Senden): t (Transaktional) oder m (Marketing)
• 45 zufällige Zeichen

Beispiele:

ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...  → Produktion Senden Transaktional
ml_sem_Xn7Kp2qR4tW9yB1cD6eF...  → Sandbox Senden Marketing
ml_pi_Mn5Jp8kL3rV6wA2xC4fG...   → Produktion Eingehend
ml_pv_Qw9Er3tY6uI1oP5aS8dF...   → Produktion Validierung

Credential-EigenschaftenLink zum Abschnitt kopieren

Beim Erstellen eines Credentials konfigurieren Sie Folgendes:

channels ist ein einzelner String, nie ein Array. Senden Sie "channels": "Api, Smtp", um beide Kanäle zu erlauben; ["Api", "Smtp"] wird mit 400 abgelehnt.

Ein Credential erstellenLink zum Abschnitt kopieren

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Transactional",
    "product": "Sending",
    "mode": "Production",
    "stream": "Transactional",
    "channels": "Api",
    "scope": "AllDomains",
    "rateLimitPerHour": 5000,
    "rateLimitPerDay": 50000
  }'

{
  "id": "n4k9pq2rt8mwxa",
  "name": "Production Transactional",
  "key": "ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...",
  "keyPrefix": "ml_pet_Ab3Kx9mN",
  "product": "sending",
  "mode": "production",
  "stream": "transactional",
  "channels": "api",
  "scope": "allDomains",
  "sandboxBehavior": "logOnly",
  "rateLimitPerHour": 5000,
  "rateLimitPerDay": 50000,
  "isActive": true,
  "createdAt": "2026-02-17T10:00:00Z"
}

Geltungsbereich: Domain-EinschränkungenLink zum Abschnitt kopieren

Standardmäßig können Credentials von jeder verifizierten Domain in Ihrem Workspace senden (AllDomains). Um ein Credential auf bestimmte Domains zu beschränken:

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing - notifications.com only",
    "product": "Sending",
    "mode": "Production",
    "stream": "Marketing",
    "channels": "Api",
    "scope": "SelectedDomains",
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

Sie können Domain-Zuweisungen auch nach der Erstellung aktualisieren:

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

IP-EinschränkungenLink zum Abschnitt kopieren

Beschränken Sie ein Credential auf bestimmte IP-Adressen oder CIDR-Bereiche:

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/allowed-ips \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "allowedIps": [
      { "ipAddress": "203.0.113.10", "description": "Production server" },
      { "ipAddress": "198.51.100.0/24", "description": "Office network" }
    ]
  }'

Wenn IP-Einschränkungen konfiguriert sind, geben API-Anfragen von nicht gelisteten IPs 403 IP_NOT_ALLOWED zurück.

Kanal-KonfigurationLink zum Abschnitt kopieren

Das Feld channels steuert, wo ein Credential authentifizieren kann:

Um ein Credential für das SMTP-Relay zu verwenden, stellen Sie sicher, dass Smtp in den Kanälen enthalten ist. Bei der Authentifizierung über SMTP verwenden Sie einen beliebigen Benutzernamen und den API-Schlüssel als Passwort.

SchlüsselrotationLink zum Abschnitt kopieren

Rotieren Sie den API-Schlüssel eines Credentials ohne Ausfallzeit mithilfe einer Übergangsfrist:

curl -X POST https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/rotate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "gracePeriodHours": 24
  }'

{
  "key": "ml_pet_Yn8Lq3rS5uW0zA4bC7dE...",
  "oldKeyExpiresAt": "2026-02-18T10:00:00Z"
}

Während der Übergangsfrist (Standard: 24 Stunden) sind sowohl der alte als auch der neue Schlüssel gültig. Nach Ablauf der Übergangsfrist funktioniert der alte Schlüssel nicht mehr.

Sandbox-ModusLink zum Abschnitt kopieren

„Sandbox“ meint zwei getrennte Dinge, die sich kombinieren:

1. Sandbox-Credentials (mode: Sandbox). Für Entwicklung, CI/CD und Staging. Was mit einem Versand geschieht, hängt vom sandboxBehavior des Credentials ab:

• LogOnly (Standard): die Anfrage wird validiert und mit 202 beantwortet, aber nichts wird zugestellt und keine Nachricht angelegt. Die Antwort enthält isSandboxed: true, sandboxReason: "credential_sandbox_mode" und leere messageIds.
• AllowListOnly: Empfänger, die zur Sandbox-Zulassungsliste Ihres Workspaces passen, erhalten die E-Mail wirklich; alle anderen stehen in rejectedRecipients mit dem Grund recipient_not_in_sandbox_allowlist. Ist kein Empfänger erlaubt, bleibt die Antwort 202 mit acceptedRecipients: [] und sandboxReason: "all_recipients_not_in_sandbox_allowlist".

Über SMTP stellt ein Sandbox-Credential nie zu: Die Nachricht wird angenommen und aufgezeichnet, aber nicht gesendet, unabhängig von sandboxBehavior.

2. Sandbox-Workspaces. Ein neuer Workspace beginnt auf der Verifizierungsstufe Sandbox (siehe Workspaces). Bis zur Verifizierung ist der Versand auch mit einem Production-Credential auf Empfänger der Zulassungsliste beschränkt. Jeder andere Empfänger wird mit 429 SENDING_BLOCKED abgelehnt („Recipient '…' is not in sandbox allowlist. Add to allowlist or complete verification.“).

Verwalten Sie die Zulassungsliste im Dashboard unter Einstellungen → Sandbox Allow List. Ein Eintrag ist eine Adresse ([email protected]) oder eine ganze Domain (*@example.com). Dieselbe Liste ist über GET /v1/account/settings/sandbox-allowlist, POST /v1/account/settings/sandbox-allowlist, DELETE /v1/account/settings/sandbox-allowlist/{email} verfügbar (Bearer-Token des Dashboards; POST nimmt email und optional description).

Credentials verwaltenLink zum Abschnitt kopieren

Credentials auflistenLink zum Abschnitt kopieren

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

Nach Produkt oder Modus filtern:

curl "https://api.mail.land/v1/credentials?product=Sending&mode=Production" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Ein Credential aktualisierenLink zum Abschnitt kopieren

curl -X PATCH https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "rateLimitPerHour": 10000,
    "isActive": false
  }'

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

Ein Credential löschenLink zum Abschnitt kopieren

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

Gibt bei Erfolg 204 No Content zurück. Gelöschte Credentials hören sofort auf zu authentifizieren. Das Löschen widerruft den Schlüssel: Das Credential bleibt in GET /v1/credentials mit isActive: false sichtbar.

RatenlimitsLink zum Abschnitt kopieren

Jedes Credential hat seine eigenen Ratenlimits, unabhängig von anderen Credentials:

Wenn ein Ratenlimit überschritten wird, gibt die API 429 mit X-RateLimit-*-Headern zurück:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708171800
Retry-After: 45

Nächste SchritteLink zum Abschnitt kopieren

• Schnellstart: senden Sie Ihre erste E-Mail
• REST-API: vollständige Referenz der Sende-API
• SMTP-Relay: authentifizieren Sie sich mit Ihrem API-Schlüssel über SMTP