Massenversand

Der Massenversand ist nur mit Marketing-Stream-Zugangsdaten verfügbar. Transaktionale Zugangsdaten geben 400 BATCH_NOT_ALLOWED_FOR_TRANSACTIONAL zurück. Dies verhindert den Missbrauch transaktionaler Streams für Massen-E-Mails.

Einen Massenversand durchführen

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

Massen-E-Mail senden

curl -X POST https://api.mail.land/v1/transactional/send-batch \
  -H "X-API-Key: ml_pem_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "[email protected]",
      "name": "Your Company"
    },
    "recipients": [
      {
        "email": "[email protected]",
        "name": "Alice",
        "variables": { "firstName": "Alice", "plan": "Pro" }
      },
      {
        "email": "[email protected]",
        "name": "Bob",
        "variables": { "firstName": "Bob", "plan": "Starter" }
      }
    ],
    "subject": "Hi {{firstName}}, check out what'\''s new",
    "htmlContent": "<h1>Hey {{firstName}}!</h1><p>Your {{plan}} plan just got an upgrade.</p>",
    "variables": {
      "companyName": "Acme Inc",
      "year": "2026"
    },
    "tags": ["product-update", "february-2026"],
    "batchName": "February Product Update"
  }'

Anfragefelder

Feld	Typ	Erforderlich	Beschreibung
`from`	object	Ja	Absenderadresse (`email` und optionaler `name`)
`recipients`	array	Ja	Liste der Empfänger (Hinweis: `recipients`, nicht `to`)
`recipients[].email`	string	Ja	Empfänger-E-Mail
`recipients[].name`	string	Nein	Anzeigename des Empfängers
`recipients[].variables`	object	Nein	Empfängerspezifische Template-Variablen
`subject`	string	Bedingt	Erforderlich, sofern keine `templateId` verwendet wird
`templateId`	string	Nein	Ein gespeichertes Template verwenden
`htmlContent`	string	Bedingt	HTML-Inhalt (erforderlich, wenn keine `templateId` angegeben)
`textContent`	string	Nein	Nur-Text-Fallback
`variables`	object	Nein	Globale Variablen. Werden unabhängig davon angewendet, ob `templateId` gesetzt ist; bei überschneidenden Schlüsseln gewinnt der empfängereigene Wert aus `recipients[].variables`
`replyTo`	string	Nein	Antwortadresse
`batchName`	string	Nein	Menschenlesbarer Name für diesen Massenversand
`tags`	array	Nein	Tags für Analysen und Webhook-Filterung
`customHeaders`	object	Nein	Benutzerdefinierte E-Mail-Header
`tracking`	object	Nein	Überschreibungen für Öffnungs-/Klick-Tracking
`ipPoolId`	string	Nein	Reserviert für dedizierte IP-Pools. Noch nicht verfügbar – wird es gesendet, kommt `400 IP_POOL_NOT_FOUND` zurück. Weglassen.
`scheduledAt`	datetime	Nein	Für zukünftige Zustellung planen, bis zu 7 Tage im Voraus
`externalBatchId`	string	Nein	Massenversand-Kennung Ihres Systems – wird sie angegeben, wird sie unverändert als `batchId` in der Antwort zurückgegeben
`priority`	enum	Nein	`Low`, `Normal` (Standard), `High`, `Critical`
`idempotencyKey`	string	Nein	Verhindert doppelte Sendungen für denselben Schlüssel. Der `X-Idempotency-Key`-Header wird bevorzugt

Beachten Sie den Feldnamenunterschied: Der Massenversand verwendet recipients, während der Einzelversand to verwendet.

Antwort

Status: 202 Accepted

Massenversand-Antwort

{
  "success": true,
  "batchId": "batch_f47ac10b58cc43729876fedcba098765",
  "messageIds": ["m_a1b2c3...", "m_d4e5f6..."],
  "totalRecipients": 2,
  "acceptedCount": 2,
  "rejectedCount": 0,
  "rejectedRecipients": [],
  "queuedAt": "2026-02-17T10:30:00Z",
  "estimatedCompletion": "2026-02-17T10:35:00Z",
  "isSandboxed": false
}

Feld	Typ	Beschreibung
`batchId`	string	Eindeutige Massenversand-Kennung
`messageIds`	array	Nachrichten-IDs pro Empfänger (mit `m_`-Präfix für Marketing)
`totalRecipients`	int	Gesamtzahl der Empfänger in der Anfrage
`acceptedCount`	int	Für die Zustellung akzeptierte Empfänger
`rejectedCount`	int	Abgelehnte Empfänger
`rejectedRecipients`	array	Details zu abgelehnten Empfängern mit Gründen
`estimatedCompletion`	datetime	Geschätzte Zeit bis zum Abschluss der Massenverarbeitung

Variablenzusammenführung

Empfängerspezifische Variablen überschreiben globale Variablen bei Schlüsselüberschneidungen:

Variablenpriorität

{
  "variables": {
    "companyName": "Acme Inc",
    "greeting": "Hello"
  },
  "recipients": [
    {
      "email": "[email protected]",
      "variables": { "greeting": "Dear valued customer" }
    },
    {
      "email": "[email protected]"
    }
  ]
}

[email protected] erhält: greeting = "Dear valued customer", companyName = "Acme Inc"
[email protected] erhält: greeting = "Hello", companyName = "Acme Inc"

Fehlerbehandlung

Massenversand-spezifische Fehler:

Status	Code	Beschreibung
`400`	`BATCH_NOT_ALLOWED_FOR_TRANSACTIONAL`	Transaktionale Zugangsdaten können keinen Massenversand durchführen
`400`	`VALIDATION_FAILED`	Maximale Empfängeranzahl pro Massenversand überschritten (10.000)
`400`	`INVALID_REQUEST`	`scheduledAt` mehr als 7 Tage im Voraus ("Cannot schedule email more than 7 days in advance")
`400`	`TEMPLATE_NOT_FOUND`	`templateId` benennt kein aktives Template dieses Kontos (wird auch für ein gelöschtes Template zurückgegeben)
`400`	`IP_POOL_NOT_FOUND`	`ipPoolId` benennt keinen diesem Konto zugewiesenen Pool
`422`	`TEMPLATE_VARIABLE_MISSING`	Für jeden Empfänger fehlt der Wert eines `{{placeholder}}` (fehlt er nur bei einigen, werden diese übersprungen und mit dem Grund `template_variable_missing: name` in `rejectedRecipients` aufgeführt). Nichts wird eingereiht
`400`	`BATCH_SEND_FAILED`	Alle Empfänger sind unterdrückt
`429`	`RATE_LIMIT_EXCEEDED`	Ratenlimit überschritten (Workspace/Plan – nicht pro Zugangsdaten)
`429`	`QUOTA_EXCEEDED`	Monatliches Kontingent erschöpft

Die für POST /v1/transactional/send dokumentierten Konto-Verifizierungs- und Policy-Codes (SENDING_BLOCKED, ACTION_REQUIRED, DAILY_LIMIT_EXCEEDED, MARKETING_PAUSED und die übrigen) gelten auch hier.

Teilerfolg ist möglich: einige Empfänger können akzeptiert werden, während andere abgelehnt werden (z. B. gesperrte Adressen). Prüfen Sie rejectedRecipients in der Antwort.

Nächste Schritte

REST API: Referenz zum Einzelversand
Templates: Templates für Massen-E-Mails erstellen
Geplante E-Mails: Massenversände für später planen

Massenversand

Einen Massenversand durchführenLink zum Abschnitt kopieren

AnfragefelderLink zum Abschnitt kopieren

AntwortLink zum Abschnitt kopieren

VariablenzusammenführungLink zum Abschnitt kopieren

FehlerbehandlungLink zum Abschnitt kopieren