E-Mail-Versand-API
Versenden Sie serverseitig über Ihre eigene Domain mit denselben Kontingenten, Abrechnungen und Limits wie beim E-Mail-Versand in der Konsole. Die Absenderdomain muss exakt einer verbundenen, aktiven Versanddomain entsprechen.
- Authentifizierung: derselbe API-Schlüssel auf Nutzerebene wie für alle anderen offenen APIs der Plattform
- Versand: POST /api/v1/mail/send; die Antwort ist nach Empfänger gegliedert. bounced_addrs ist die einzige Grundlage zur Bereinigung Ihrer Liste
- Idempotenz: Mit dem Header Idempotency-Key führen wiederholte Anfragen mit demselben Schlüssel genau einen Versand aus, ohne doppelte Zustellung oder Abrechnung
- Nachrichtenverläufe: Übergeben Sie in_reply_to und die vollständige references-Kette, damit Antworten im ursprünglichen Gespräch des Empfängers erscheinen
- Kontingent und Domains: Fragen Sie das verbleibende Tageskontingent und nutzbare Versanddomains ab, um den Durchsatz in Ihrem System zu begrenzen
- Codebeispiele: minimale, funktionsfähige Beispiele für cURL / Node.js / Python / Go / PHP, jeweils mit Idempotenz und Behandlung dauerhafter Zustellfehler
POST / GET /api/v1/mail/*
Übersicht
Serverseitig über eigene Domains senden. Es gelten dieselben Kontingente, Abrechnungsregeln und Limits wie in der Konsole.
Aktivieren Sie den E-Mail-Versand in der Konsole und richten Sie mindestens eine Domain mit dem Status Aktiv ein. Sendungen von nicht aktiven Domains werden abgelehnt.
Authentifizierung
Verwendet denselben Konto-API-Schlüssel wie die übrige Plattform. Erstellen Sie ihn unter Tools und Einstellungen → API-Verwaltung.
Konsole → Tools und Einstellungen → API-Verwaltung → Schlüssel erstellen. Derselbe Schlüssel funktioniert für Energie-, virtuelle Karten-, E-Mail- und Wechselkurs-APIs; die erreichbaren Endpunkte hängen von seinen Berechtigungen ab.
E-Mail senden
POST /api/v1/mail/send
Die From-Domain muss genau mit einer eingerichteten, aktiven Versanddomain übereinstimmen.
Versandlimits
- to + cc + bcc dürfen insgesamt höchstens 50 Empfänger enthalten
- 5 MiB je Nachricht einschließlich Anhängen (dekodiert gemessen)
- 998 Zeichen (Zeichen zählen, nicht Bytes — Betreffe mit Nicht-ASCII-Zeichen sind nicht benachteiligt)
- Bis zu 32 Anhänge; eingebettete Anhänge benötigen eine content_id
- Benutzerdefinierte Header insgesamt 16 KB, je Headerwert 2048 Bytes
Antwort
Ergebnisse werden je Empfänger gruppiert, nicht als einzelnes allgemeines Erfolgskennzeichen.
Bei fünf Empfängern können 2 Zustellungen, 1 Nachricht in der Warteschlange und 2 permanente Unzustellbarkeiten auftreten. bounced_addrs ist Ihre einzige Quelle zur Listenpflege — es gibt keinen Webhook für Unzustellbarkeiten. Wenn Sie dieses Feld verwerfen, ist die Information verloren; Sie senden weiter an ungültige Adressen und bezahlen dafür.
Idempotenz
Mit dem Header Idempotency-Key führt das erneute Senden desselben Schlüssels nur zu einem Versand.
Immer dann, wenn Ihr Aufruf automatisch wiederholt werden kann — Zeitüberschreitungen, Auftragswarteschlangen, SDK-Wiederholungen. Ohne diesen Header kann eine einzige Netzwerkstörung zu doppelter Zustellung und doppelter Abrechnung führen; beides lässt sich nicht rückgängig machen. Verwenden Sie einen Geschäftsschlüssel, z. B. eine Auftragsnummer.
Konversationszuordnung
Geben Sie bei Antworten in_reply_to und references an, damit die E-Mail in der ursprünglichen Konversation landet; ohne sie eröffnet jede Antwort eine neue Konversation beim Empfänger. Senden Sie die vollständige references-Kette — nur mit in_reply_to können manche Clients Konversationen mit mehr als zwei Nachrichten aufteilen.
Kontingent und Domains
Verbleibendes Tagesvolumen und verfügbare Versanddomains prüfen, um auf Ihrer Seite die Versandrate zu begrenzen.
Codebeispiele
Minimale funktionsfähige Beispiele je Programmiersprache, jeweils mit Idempotenz und Behandlung permanenter Unzustellbarkeiten.
E-Mail-Versand ist kostenpflichtig. Neue API-Schlüssel verlangen standardmäßig signierte Anfragen für kostenpflichtige Endpunkte; deshalb nutzen alle folgenden Beispiele Signaturversion 2 (Header X-Sign-Version: 2 senden). Die Signaturzeichenfolge besteht aus 7 durch \n verbundenen Zeilen ohne abschließenden Zeilenumbruch: NEXCORE-HMAC-SHA256-V2, timestamp, nonce, HTTP-Methode in Großbuchstaben, Pfad, Query-Zeichenfolge und SHA-256-Hash des Inhalts als Hexadezimaltext in Kleinbuchstaben. X-Signature ist HMAC-SHA256(Secret Key, Signaturzeichenfolge) als Hexadezimaltext in Kleinbuchstaben. timestamp ist Unix-Zeit in Sekunden, nonce maximal 64 Bytes; die Query-Zeichenfolge hat kein führendes "?" und muss exakt der gesendeten entsprechen (leere Zeile, wenn nicht vorhanden). Der Inhaltshash wird über die exakt gesendeten Bytes berechnet. Deaktivieren Sie „Signierte Anfragen für kostenpflichtige Vorgänge und sensible Daten erforderlich“, funktionieren auch X-API-Key + X-Secret-Key allein; dies wird nicht empfohlen.
Häufig gestellte Fragen
Bedeutet HTTP 200, dass alle Empfänger die E-Mail erhalten haben?
Nein. Ergebnisse werden nach Empfänger aufgeteilt: Von fünf Empfängern können 2 beliefert, 1 eingereiht und 2 dauerhaft abgewiesen sein. Es gibt keinen Webhook für Zustellfehler; bounced_addrs ist daher die einzige Grundlage zur Listenbereinigung. Stellen Sie den Versand an diese Adressen sofort ein.
Wann ist ein Idempotency-Key erforderlich?
Immer, wenn ein Aufruf automatisch wiederholt werden kann: nach Zeitüberschreitungen, erneuter Jobzustellung oder durch SDK-Wiederholungen. Ohne ihn kann eine kurze Netzwerkstörung zwei E-Mails und eine doppelte Abrechnung verursachen. Beides lässt sich nicht rückgängig machen. Nutzen Sie einen Geschäftsschlüssel wie die Bestell-ID.
Verwandte Seiten: API-Dokumentation · SMTP-Aggregations-API · Die SMTP-Aggregations-API verwenden
Wird geladen…