E-Mail senden
Senden Sie eine Transaktions- oder Marketing-E-Mail an einen oder mehrere Empfänger. Unterstützt HTML-Inhalte, Anhänge, Reply-To und Marketing-Header.
https://mail.sendcorex.com/v3.0/sendSie möchten an mehrere Empfänger gleichzeitig senden? Übergeben Sie to als Array – siehe Batch-E-Mails senden.
Body-Parameter
tostring | string[]erforderlichE-Mail-Adresse des Empfängers oder Array mit bis zu 50 Adressen.
z. B.
"user@example.com" or ["a@x.com", "b@x.com"]fromstringerforderlichE-Mail-Adresse des Absenders. Muss zu einer verifizierten Domain in Ihrem Konto gehören.
senderNamestringerforderlichAnzeigename im Posteingang des Empfängers.
subjectstringerforderlichBetreffzeile der E-Mail. HTML wird hier nicht unterstützt.
bodystringerforderlichHTML-Inhalt des E-Mail-Texts.
replyTostringoptionalAntwortadresse (Reply-To). Wird sie weggelassen, gilt die Absenderadresse.
transactionalbooleanoptionalAuf true setzen, um die E-Mail als Transaktions-E-Mail zu kennzeichnen. Standard: false.
attachmentsobject[]optionalArray von Anhangsobjekten. Siehe Anhänge senden für alle Details.
retryRateLimitedintegeroptionalWie viele 30-Minuten-Zyklen weiter versucht wird, wenn der Provider ein Rate Limit setzt (0–24, Standard 25). Siehe Zustelloptionen für alle Details.
retryUnavailableintegeroptionalWie oft nach einem temporären Fehler erneut versucht wird (0–30). Zusammen mit retryUnavailableSeconds (10–3600) verwenden. Siehe Zustelloptionen für alle Details.
ignoreHardBouncebooleanoptionalAuch senden, wenn die Adresse in den letzten 90 Tagen einen Hard Bounce hatte. Standard: false. Siehe Zustelloptionen für alle Details.
Schnellstart
import axios from 'axios';
const response = await axios.post(
'https://mail.sendcorex.com/v3.0/send',
{
to: 'user@example.com',
from: 'noreply@yourdomain.com',
senderName: 'My App',
subject: 'Welcome aboard!',
body: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
replyTo: 'support@yourdomain.com',
},
{
headers: { Authorization: process.env.SENDCOREX_API_KEY },
}
);
const { id, ids, recipients } = response.data;Antwort
{
"success": true,
"message": "Email queued successfully",
"code": "EMAIL_QUEUED_SUCCESS",
"id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
"ids": [
{ "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f", "recipient": "user@example.com" }
],
"recipients": 1,
"scheduledAt": null
}Idempotente Anfragen
Sende den Header Idempotency-Key mit einem eindeutigen Wert (wir empfehlen eine UUID v4), um POST /v3.0/send sicher zu wiederholen. Bricht die Verbindung ab oder gibt es einen Timeout, wiederhole mit demselben Schlüssel und demselben Body: Wir liefern die ursprüngliche Antwort (gleiche E-Mail-id) und die E-Mail wird nicht doppelt gesendet.
POST /v3.0/send
Authorization: Bearer <api_key>
Idempotency-Key: 3f1c9a52-6b1e-4f0e-9c2a-8d7e5b4a1f00
Content-Type: application/jsonSchlüssel gelten 24 Stunden und nur für dein Konto.
Erlaubte Zeichen: Buchstaben, Zahlen,
_ - : .(1–255 Zeichen).Eine wiederholte Antwort hat den Header
Idempotent-Replayed: true.Nutze für jede neue E-Mail einen neuen Schlüssel. Ein Schlüssel mit anderem Body liefert
422 IDEMPOTENCY_KEY_REUSED.Wird die erste Anfrage noch verarbeitet, erhältst du
409 IDEMPOTENCY_IN_PROGRESSmitRetry-After: 1. Warte und wiederhole mit demselben Schlüssel.Serverfehler (
5xx) und Rate-Limits (429) werden nicht gespeichert: Ein Retry mit demselben Schlüssel sendet ganz normal.Ohne den Header funktioniert der Endpoint wie bisher.
Empfohlener Retry: bei Netzwerkfehler, Timeout, 409, 429 oder 5xx mit demselben Schlüssel und exponentiellem Backoff wiederholen (1 s, 2 s, 4 s…, bis zu 5 Versuche).
Beispiel: UUID-Schlüssel + Retry mit Backoff
import { randomUUID } from 'node:crypto';
const RETRY_STATUS = new Set([409, 429, 500, 502, 503, 504]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function sendEmail(email) {
const key = randomUUID(); // one key per email, reused on every retry
const body = JSON.stringify(email); // same body on every retry
for (let attempt = 1; attempt <= 5; attempt++) {
try {
const res = await fetch('https://mail.sendcorex.com/v3.0/send', {
method: 'POST',
headers: {
Authorization: process.env.SENDCOREX_API_KEY,
'Idempotency-Key': key,
'Content-Type': 'application/json',
},
body,
signal: AbortSignal.timeout(15_000),
});
if (!RETRY_STATUS.has(res.status)) {
const data = await res.json();
if (!res.ok) throw new Error(data.code || 'SEND_FAILED');
// Idempotent-Replayed: true → this is the original response (not sent twice)
return { ...data, replayed: res.headers.get('Idempotent-Replayed') === 'true' };
}
if (attempt === 5) throw new Error('HTTP ' + res.status);
const retryAfter = Number(res.headers.get('Retry-After')) * 1000;
await sleep(retryAfter || 1000 * 2 ** (attempt - 1));
} catch (err) {
// network error or timeout: retry with the same key
if (err.message?.startsWith('HTTP ') || attempt === 5 || (err.name !== 'TypeError' && err.name !== 'TimeoutError')) throw err;
await sleep(1000 * 2 ** (attempt - 1));
}
}
}
const result = await sendEmail({
to: 'user@example.com',
from: 'noreply@yourdomain.com',
senderName: 'My App',
subject: 'Your receipt',
body: '<p>Thanks for your order.</p>',
});
console.log(result.id, result.replayed);Meine Nachrichten werden als Spam markiert
Jede Nachricht durchläuft unseren Anti-Spam-Filter. Wird eine markiert, liefert die Anfrage 403 mit dem Code SPAM_DETECTED zurück und die E-Mail wird in Quarantäne gehalten.
Als Spam markiert
{
"error": "Email content flagged as spam.",
"code": "SPAM_DETECTED",
"detectionId": "9c1e5a7d-2b4f-4e8a-a6d3-0f1b2c3d4e5f",
"quarantine_id": "qtn_3f2a1b4c8e9d4f7a",
"release_instructions": "POST /v3.0/quarantine/release with { quarantine_id }",
"expires_in": "3 hours"
}codeBei dieser Antwort immer SPAM_DETECTED.
detectionIdKennung dieser Erkennung. Geben Sie sie an, wenn Sie den Support kontaktieren.
quarantine_idÜbergeben Sie diese an /quarantine/release, um die E-Mail nach der Prüfung zu senden.
release_instructionsWie die E-Mail freigegeben wird.
expires_inWie lange der Quarantäne-Eintrag aufbewahrt wird, bevor er abläuft.
Eine E-Mail in Quarantäne wird nicht zugestellt. Verwenden Sie /quarantine/release, um sie nach der Prüfung zu senden. Der Quarantäne-Eintrag läuft nach 3 Stunden ab.
Wenn quarantine_id, release_instructions und expires_in als null zurückkommen, wurde die E-Mail ohne Quarantäne-Eintrag blockiert. Sie kann nicht freigegeben werden: Korrigieren Sie den Inhalt und senden Sie sie erneut.
Fehler
Alle Fehlercodes →Fehler liefern ein JSON-Objekt mit error, code und responseTime.
- 401
MISSING_AUTH_HEADERKein Authorization-Header vorhanden.
- 401
INVALID_API_KEYDer API-Schlüssel ist ungültig oder widerrufen.
- 401
ACCOUNT_BLOCKEDDas Konto wurde gesperrt.
- 401
NO_CREDITS_LEFTNicht genug E-Mail-Credits für alle Empfänger. Jede Adresse in to, cc und bcc verbraucht 1 Credit.
- 401
DOMAIN_NOT_VALIDATEDAbsender-Domain nicht verifiziert.
- 401
LISTED_SPAM_HAUSDie Absender-Domain ist bei Spamhaus gelistet.
- 401
ISP_DOMAIN_BLOCKEDDer Versand von bekannten Domains (gmail.com, outlook.com usw.) ist nicht erlaubt.
- 401
FROM_HEADER_DOMAIN_MISMATCHDomain des From-Headers ist für diesen Absender nicht autorisiert.
- 401
USER_NOT_FOUNDBenutzer nicht gefunden.
- 401
MISSING_USER_PRIVILEGESFehlende Benutzerrechte.
- 401
EMAIL_CREDITS_NOT_FOUNDFehler beim Abrufen der E-Mail-Credits.
- 401
EMAIL_NOT_VALIDATEDDie E-Mail-Adresse des Kontos wurde noch nicht verifiziert.
- 429
CREDENTIAL_TEMPORARILY_BLOCKEDAPI-Schlüssel wegen wiederholter Richtlinienverstöße vorübergehend gesperrt.
- 429
IP_TEMPORARILY_BLOCKEDAnfragende IP wegen wiederholter Richtlinienverstöße vorübergehend gesperrt.
- 429
TOO_MANY_CONCURRENT_CONNECTIONSZu viele gleichzeitige Anfragen von dieser IP. Versuchen Sie es gleich erneut.
- 400
INVALID_JSONDer Request-Body ist kein gültiges JSON.
- 400
MISSING_FROMDas Feld from fehlt oder ist leer.
- 400
INVALID_FROM_FORMATDas Feld from muss eine gültige E-Mail-Adresse sein.
- 400
MISSING_SENDERNAMEDas Feld senderName fehlt oder ist leer.
- 400
INVALID_SENDERNAME_FORMATDas Feld senderName enthält ungültige Zeichen.
- 400
MISSING_SUBJECTDas Feld subject fehlt oder ist leer.
- 400
MISSING_BODYDas Feld body fehlt oder ist leer.
- 400
MISSING_TOADDRESSDas Feld to fehlt oder ist leer.
- 400
MISSING_TODas Feld to fehlt oder ist leer.
- 400
INVALID_TOADDRESSEine oder mehrere Empfängeradressen sind fehlerhaft.
- 400
TOADDRESS_LIMIT_EXCEEDEDMehr als 50 Empfänger im Array to.
- 400
INVALID_CCADDRESSEine oder mehrere cc-Adressen sind fehlerhaft.
- 400
INVALID_BCCADDRESSEine oder mehrere bcc-Adressen sind fehlerhaft.
- 400
RECIPIENT_LIMIT_EXCEEDEDto, cc und bcc haben zusammen mehr als 50 eindeutige Empfänger.
- 400
INVALID_SCHEDULED_ATscheduled_at ist kein gültiges Datum oder liegt in der Vergangenheit.
- 400
INVALID_SENDER_FORMATDas Format der Absenderadresse ist ungültig.
- 400
HEADER_NOT_ALLOWEDDer Schlüssel des eigenen Headers steht nicht auf der Liste der erlaubten (List-Unsubscribe, List-Id, X-* usw.).
- 400
INVALID_HEADER_VALUEDer Header-Wert enthält ungültige Zeichen (CR/LF nicht erlaubt).
- 400
DANGEROUS_ATTACHMENTEin oder mehrere Anhänge wurden aus Sicherheitsgründen blockiert.
- 400
INVALID_ATTACHMENTDer Inhalt eines Anhangs ist kein gültiges base64.
- 400
MISSING_UNSUBSCRIBE_PLACEHOLDERunsubscribe ist true, aber der body enthält keinen Abmelde-Platzhalter ([unsubscribe_url], [unsubscribe], [unsub_url] oder [opt_out_url]).
- 403
ACCOUNT_RESTRICTEDDas Konto ist vorübergehend eingeschränkt.
- 403
DAILY_LIMITTägliches Versandlimit erreicht.
- 403
MARKETING_LIMIT_REACHEDTägliches Marketing-Limit des Free-Plans erreicht: 30 Marketing- oder Kaltakquise-E-Mails pro Tag, pro Empfänger gezählt in einem gleitenden 24-Stunden-Fenster. Die Antwort enthält limit, used, recipients und upgradeUrl. Transaktionale E-Mails werden weiter versendet; nichts wird in die Warteschlange gestellt.
- 403
FORBIDDEN_HTML_CONTENTDas HTML enthält aktive Inhalte, die in E-Mails nicht erlaubt sind (script, iframe, form, input, button, embed, object, svg, on*-Handler, javascript:-Links, meta refresh…). Die Antwort listet die Funde auf. Verwenden Sie ein gestyltes <a> statt Buttons oder Formularen.
- 403
SPAM_DETECTEDE-Mail-Inhalt als Spam erkannt. Die Antwort enthält die quarantine_id und Anweisungen zur Freigabe.
- 403
SENDER_NAME_MISMATCHMehrere Absendernamen für dieselbe Adresse erkannt.
- 403
FOLLOWUP_PATTERN_DETECTEDE-Mail-Inhalt als wiederholtes verdächtiges Follow-up-Muster erkannt.
- 403
SCAM_PATTERN_DETECTEDE-Mail-Inhalt als Betrugsmuster erkannt.
- 403
ACCOUNT_SUSPENDED_SPOOFINGKonto wegen wiederholter Versuche, den From-Header zu fälschen, gesperrt.
- 409
IDEMPOTENCY_IN_PROGRESSEine Anfrage mit demselben Idempotency-Key wird noch verarbeitet. Warte (Retry-After: 1) und wiederhole mit demselben Schlüssel.
- 422
IDEMPOTENCY_KEY_REUSEDDieser Idempotency-Key wurde bereits mit einem anderen Body verwendet. Nutze für jede neue E-Mail einen neuen Schlüssel.
- 500
INTERNAL_SERVER_ERRORUnerwarteter Serverfehler. Versuchen Sie es erneut.
- 500
PARSE_ERRORE-Mail-Inhalt konnte nicht verarbeitet werden (MIME-Parse-Fehler).
- 500
PERSIST_FAILEDE-Mail konnte nicht in die Warteschlange gestellt werden (Fehler beim Speichern in der Datenbank).
- 503
AUTH_UNAVAILABLEDer API-Schlüssel konnte gerade nicht geprüft werden. Versuchen Sie es erneut.
- 503
UNSUBSCRIBE_UNAVAILABLEDienst für Abmeldelinks vorübergehend nicht verfügbar. Versuchen Sie es später erneut.