REST API

Senden Sie transaktionale E-Mails über POST /v1/transactional/send. Dies ist die primäre Methode zum Versenden von E-Mails über MailLand.

AuthentifizierungLink zum Abschnitt kopieren

Fügen Sie Ihren API-Schlüssel im X-API-Key-Header ein:

X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...

Die Zugangsdaten müssen den Api-Kanal aktiviert haben und Sending-Produktzugangsdaten sein.

Eine einzelne E-Mail sendenLink zum Abschnitt kopieren

POST https://api.mail.land/v1/transactional/send

curl -X POST https://api.mail.land/v1/transactional/send \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]"},
    "to": [{"email": "[email protected]"}],
    "subject": "Hello from MailLand",
    "htmlContent": "<p>Your email content here</p>"
  }'

AnfragekörperLink zum Abschnitt kopieren

{
  "from": {
    "email": "[email protected]",
    "name": "Your App"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "Jane Doe",
      "variables": {
        "firstName": "Jane",
        "orderNumber": "ORD-12345"
      }
    }
  ],
  "subject": "Your order #{{orderNumber}} has shipped",
  "htmlContent": "<h1>Hi {{firstName}},</h1><p>Your order #{{orderNumber}} is on its way.</p>",
  "textContent": "Hi {{firstName}}, Your order #{{orderNumber}} is on its way.",
  "replyTo": "[email protected]",
  "tags": ["order-shipped", "transactional"],
  "customHeaders": {
    "X-Entity-Ref-ID": "order-12345"
  },
  "tracking": {
    "opens": true,
    "clicks": true
  },
  "priority": "High",
  "idempotencyKey": "order-12345-shipped-v1"
}

FeldreferenzLink zum Abschnitt kopieren

AnhängeLink zum Abschnitt kopieren

Jeder Anhang erfordert drei Felder:

{
  "attachments": [
    {
      "fileName": "invoice.pdf",
      "contentType": "application/pdf",
      "content": "JVBERi0xLjQKJ...",
      "inline": false
    },
    {
      "fileName": "logo.png",
      "contentType": "image/png",
      "content": "iVBORw0KGgoAAAA...",
      "contentId": "company-logo",
      "inline": true
    }
  ]
}

AntwortLink zum Abschnitt kopieren

Status: 202 Accepted

{
  "success": true,
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageIds": ["t_a1b2c3d4e5f6..."],
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [],
  "queuedAt": "2026-02-17T10:30:00Z",
  "isSandboxed": false
}

Abgelehnte EmpfängerLink zum Abschnitt kopieren

Empfänger können aus verschiedenen Gründen abgelehnt werden:

{
  "success": true,
  "jobId": "...",
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [
    {
      "email": "[email protected]",
      "reason": "Suppressed"
    },
    {
      "email": "[email protected]",
      "reason": "domain_typo",
      "suggestion": "[email protected]"
    }
  ]
}

Häufige Ablehnungsgründe:

• Suppressed: Adresse auf der Unterdrückungsliste (frühere Bounces/Beschwerden)
• disposable_domain: Wegwerf-E-Mail-Anbieter erkannt
• domain_typo: wahrscheinlicher Tippfehler in der Domain (enthält suggestion-Feld)

VorabprüfungLink zum Abschnitt kopieren

Überprüfen Sie Ihre Sendefähigkeit, bevor Sie die eigentliche Anfrage stellen:

GET https://api.mail.land/v1/transactional/send/check?recipientCount=1

curl https://api.mail.land/v1/transactional/send/check?recipientCount=1 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

{
  "canSend": true,
  "rateLimitStatus": {
    "currentSecond": 2,
    "limitPerSecond": 50,
    "currentHour": 450,
    "limitPerHour": 5000,
    "currentDay": 8200,
    "limitPerDay": 50000
  },
  "monthlyUsed": 125000,
  "monthlyLimit": 500000
}

Wenn canSend false ist, erklärt das reason-Feld den Grund (Ratenlimit, Kontingent, Kontostatus usw.).

IdempotenzLink zum Abschnitt kopieren

Ein Wiederholungsversuch nach einem Netzwerk-Timeout darf die E-Mail nicht zweimal zustellen. Mit einem Idempotenz-Schlüssel gibt ein erneuter Aufruf die ursprüngliche Antwort zurück, statt erneut zu senden.

Schlüssel als Header senden (empfohlen):

X-Idempotency-Key: order-12345-shipped-v1

Alternativ das Body-Feld idempotencyKey. Beide werden akzeptiert; beide gemeinsam nur bei identischen Werten.

RegelnLink zum Abschnitt kopieren

• Geltungsbereich. X-Idempotency-Key wird ausschließlich von POST /v1/transactional/send und POST /v1/transactional/send-batch gelesen.
• Format. 1–255 Zeichen: Buchstaben, Ziffern, _ und -. Schlüssel werden exakt verglichen: ohne Trimmen, ohne Groß-/Kleinschreibungsangleich.
• Zeitfenster. Ein Schlüssel bleibt 24 Stunden wiederholbar. Danach gilt er als neue Anfrage.
• Wiedergabe. Ein Wiederholungsversuch im Zeitfenster liefert die ursprüngliche Antwort unverändert (gleiche IDs, gleicher Status) und sendet nichts.
• Eindeutigkeit. Schlüssel sind pro Konto eindeutig. Ein Schlüssel für einen anderen Endpunkt wird mit 409 abgelehnt; pro Vorgang einen eigenen Schlüssel verwenden.

Korrelations-IDLink zum Abschnitt kopieren

Verfolgen Sie Anfragen systemübergreifend durch Angabe einer Korrelations-ID:

X-Correlation-ID: my-app-order-12345

oder

X-Request-ID: my-app-order-12345

Die Korrelations-ID erscheint in Logs und im Activity Stream.

Ratenlimit-HeaderLink zum Abschnitt kopieren

Erfolgreiche Antworten enthalten Pro-IP-Ratenlimit-Informationen:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295

Bei Ratenlimitierung (429) durch die Sende-Policy-Engine gibt ein Retry-After-Header die Wartezeit in Sekunden an:

Retry-After: 30

Eine transaktionale Anfrage darf bis zu 5 Empfänger nennen, und jeder zählt gegen Ihre Ratenlimits. Ist das mehr als Ihr Pro-Sekunde-Kontingent (zum Beispiel 1 pro Sekunde bei einem Plan mit 60 pro Minute), wird die Anfrage angenommen, wenn in derselben Sekunde keine andere Anfrage angenommen wurde; andernfalls erhält sie 429 mit Retry-After: 1 und ist bei einem erneuten Versuch in der nächsten Sekunde erfolgreich, im Rahmen Ihres Pro-Minute-Limits. Siehe Ratenbegrenzungen.

Ein IP-Level-429 enthält zusätzlich X-RateLimit-Reset als ISO-8601-UTC-Zeit.

FehlerantwortenLink zum Abschnitt kopieren

Alle Fehler geben einen JSON-Körper zurück:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "timestamp": "2026-02-17T10:30:00Z",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

FehlercodesLink zum Abschnitt kopieren

Transaktionales EmpfängerlimitLink zum Abschnitt kopieren

Transaktionale Zugangsdaten erzwingen maximal 5 Empfänger pro Sendeanfrage. Dies verhindert den Missbrauch transaktionaler Streams für den Massenversand. Falls Sie mehr Empfänger benötigen, verwenden Sie Marketing-Zugangsdaten mit Batch-Versand.

Templates verwendenLink zum Abschnitt kopieren

Verwenden Sie anstelle von Inline-HTML ein gespeichertes Template:

{
  "from": { "email": "[email protected]" },
  "to": [
    {
      "email": "[email protected]",
      "variables": {
        "firstName": "Jane",
        "resetLink": "https://app.example.com/reset?token=abc123"
      }
    }
  ],
  "templateId": "t8x2m4q9zk7wpr",
  "variables": {
    "companyName": "Acme Inc"
  }
}

Der subject stammt aus dem Template. Bei übereinstimmenden Schlüsseln überschreibt der empfängereigene Wert aus to[].variables die globalen variables, dieselbe Regel wie bei Inline-Inhalt. Siehe Templates zum Erstellen und Verwalten von Templates.

Nächste SchritteLink zum Abschnitt kopieren

• Batch-Versand: an mehrere Empfänger gleichzeitig senden
• SMTP-Relay: per SMTP statt REST senden
• Templates: wiederverwendbare E-Mail-Templates erstellen
• Geplante E-Mails: E-Mails für zukünftige Zustellung planen