E-Mail

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.

POSThttps://mail.sendcorex.com/v3.0/send
i

Sie möchten an mehrere Empfänger gleichzeitig senden? Übergeben Sie to als Array – siehe Batch-E-Mails senden.

Body-Parameter

  • tostring | string[]erforderlich

    E-Mail-Adresse des Empfängers oder Array mit bis zu 50 Adressen.

    z. B. "user@example.com" or ["a@x.com", "b@x.com"]

  • fromstringerforderlich

    E-Mail-Adresse des Absenders. Muss zu einer verifizierten Domain in Ihrem Konto gehören.

  • senderNamestringerforderlich

    Anzeigename im Posteingang des Empfängers.

  • subjectstringerforderlich

    Betreffzeile der E-Mail. HTML wird hier nicht unterstützt.

  • bodystringerforderlich

    HTML-Inhalt des E-Mail-Texts.

  • replyTostringoptional

    Antwortadresse (Reply-To). Wird sie weggelassen, gilt die Absenderadresse.

  • transactionalbooleanoptional

    Auf true setzen, um die E-Mail als Transaktions-E-Mail zu kennzeichnen. Standard: false.

  • attachmentsobject[]optional

    Array von Anhangsobjekten. Siehe Anhänge senden für alle Details.

  • retryRateLimitedintegeroptional

    Wie viele 30-Minuten-Zyklen weiter versucht wird, wenn der Provider ein Rate Limit setzt (0–24, Standard 25). Siehe Zustelloptionen für alle Details.

  • retryUnavailableintegeroptional

    Wie oft nach einem temporären Fehler erneut versucht wird (0–30). Zusammen mit retryUnavailableSeconds (10–3600) verwenden. Siehe Zustelloptionen für alle Details.

  • ignoreHardBouncebooleanoptional

    Auch 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.

HTTP
POST /v3.0/send
Authorization: Bearer <api_key>
Idempotency-Key: 3f1c9a52-6b1e-4f0e-9c2a-8d7e5b4a1f00
Content-Type: application/json
  • Schlü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_PROGRESS mit Retry-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.

403

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"
}
  • code

    Bei dieser Antwort immer SPAM_DETECTED.

  • detectionId

    Kennung 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_instructions

    Wie die E-Mail freigegeben wird.

  • expires_in

    Wie 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 liefern ein JSON-Objekt mit error, code und responseTime.

  • 401MISSING_AUTH_HEADER

    Kein Authorization-Header vorhanden.

  • 401INVALID_API_KEY

    Der API-Schlüssel ist ungültig oder widerrufen.

  • 401ACCOUNT_BLOCKED

    Das Konto wurde gesperrt.

  • 401NO_CREDITS_LEFT

    Nicht genug E-Mail-Credits für alle Empfänger. Jede Adresse in to, cc und bcc verbraucht 1 Credit.

  • 401DOMAIN_NOT_VALIDATED

    Absender-Domain nicht verifiziert.

  • 401LISTED_SPAM_HAUS

    Die Absender-Domain ist bei Spamhaus gelistet.

  • 401ISP_DOMAIN_BLOCKED

    Der Versand von bekannten Domains (gmail.com, outlook.com usw.) ist nicht erlaubt.

  • 401FROM_HEADER_DOMAIN_MISMATCH

    Domain des From-Headers ist für diesen Absender nicht autorisiert.

  • 401USER_NOT_FOUND

    Benutzer nicht gefunden.

  • 401MISSING_USER_PRIVILEGES

    Fehlende Benutzerrechte.

  • 401EMAIL_CREDITS_NOT_FOUND

    Fehler beim Abrufen der E-Mail-Credits.

  • 401EMAIL_NOT_VALIDATED

    Die E-Mail-Adresse des Kontos wurde noch nicht verifiziert.

  • 429CREDENTIAL_TEMPORARILY_BLOCKED

    API-Schlüssel wegen wiederholter Richtlinienverstöße vorübergehend gesperrt.

  • 429IP_TEMPORARILY_BLOCKED

    Anfragende IP wegen wiederholter Richtlinienverstöße vorübergehend gesperrt.

  • 429TOO_MANY_CONCURRENT_CONNECTIONS

    Zu viele gleichzeitige Anfragen von dieser IP. Versuchen Sie es gleich erneut.

  • 400INVALID_JSON

    Der Request-Body ist kein gültiges JSON.

  • 400MISSING_FROM

    Das Feld from fehlt oder ist leer.

  • 400INVALID_FROM_FORMAT

    Das Feld from muss eine gültige E-Mail-Adresse sein.

  • 400MISSING_SENDERNAME

    Das Feld senderName fehlt oder ist leer.

  • 400INVALID_SENDERNAME_FORMAT

    Das Feld senderName enthält ungültige Zeichen.

  • 400MISSING_SUBJECT

    Das Feld subject fehlt oder ist leer.

  • 400MISSING_BODY

    Das Feld body fehlt oder ist leer.

  • 400MISSING_TOADDRESS

    Das Feld to fehlt oder ist leer.

  • 400MISSING_TO

    Das Feld to fehlt oder ist leer.

  • 400INVALID_TOADDRESS

    Eine oder mehrere Empfängeradressen sind fehlerhaft.

  • 400TOADDRESS_LIMIT_EXCEEDED

    Mehr als 50 Empfänger im Array to.

  • 400INVALID_CCADDRESS

    Eine oder mehrere cc-Adressen sind fehlerhaft.

  • 400INVALID_BCCADDRESS

    Eine oder mehrere bcc-Adressen sind fehlerhaft.

  • 400RECIPIENT_LIMIT_EXCEEDED

    to, cc und bcc haben zusammen mehr als 50 eindeutige Empfänger.

  • 400INVALID_SCHEDULED_AT

    scheduled_at ist kein gültiges Datum oder liegt in der Vergangenheit.

  • 400INVALID_SENDER_FORMAT

    Das Format der Absenderadresse ist ungültig.

  • 400HEADER_NOT_ALLOWED

    Der Schlüssel des eigenen Headers steht nicht auf der Liste der erlaubten (List-Unsubscribe, List-Id, X-* usw.).

  • 400INVALID_HEADER_VALUE

    Der Header-Wert enthält ungültige Zeichen (CR/LF nicht erlaubt).

  • 400DANGEROUS_ATTACHMENT

    Ein oder mehrere Anhänge wurden aus Sicherheitsgründen blockiert.

  • 400INVALID_ATTACHMENT

    Der Inhalt eines Anhangs ist kein gültiges base64.

  • 400MISSING_UNSUBSCRIBE_PLACEHOLDER

    unsubscribe ist true, aber der body enthält keinen Abmelde-Platzhalter ([unsubscribe_url], [unsubscribe], [unsub_url] oder [opt_out_url]).

  • 403ACCOUNT_RESTRICTED

    Das Konto ist vorübergehend eingeschränkt.

  • 403DAILY_LIMIT

    Tägliches Versandlimit erreicht.

  • 403MARKETING_LIMIT_REACHED

    Tä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.

  • 403FORBIDDEN_HTML_CONTENT

    Das 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.

  • 403SPAM_DETECTED

    E-Mail-Inhalt als Spam erkannt. Die Antwort enthält die quarantine_id und Anweisungen zur Freigabe.

  • 403SENDER_NAME_MISMATCH

    Mehrere Absendernamen für dieselbe Adresse erkannt.

  • 403FOLLOWUP_PATTERN_DETECTED

    E-Mail-Inhalt als wiederholtes verdächtiges Follow-up-Muster erkannt.

  • 403SCAM_PATTERN_DETECTED

    E-Mail-Inhalt als Betrugsmuster erkannt.

  • 403ACCOUNT_SUSPENDED_SPOOFING

    Konto wegen wiederholter Versuche, den From-Header zu fälschen, gesperrt.

  • 409IDEMPOTENCY_IN_PROGRESS

    Eine Anfrage mit demselben Idempotency-Key wird noch verarbeitet. Warte (Retry-After: 1) und wiederhole mit demselben Schlüssel.

  • 422IDEMPOTENCY_KEY_REUSED

    Dieser Idempotency-Key wurde bereits mit einem anderen Body verwendet. Nutze für jede neue E-Mail einen neuen Schlüssel.

  • 500INTERNAL_SERVER_ERROR

    Unerwarteter Serverfehler. Versuchen Sie es erneut.

  • 500PARSE_ERROR

    E-Mail-Inhalt konnte nicht verarbeitet werden (MIME-Parse-Fehler).

  • 500PERSIST_FAILED

    E-Mail konnte nicht in die Warteschlange gestellt werden (Fehler beim Speichern in der Datenbank).

  • 503AUTH_UNAVAILABLE

    Der API-Schlüssel konnte gerade nicht geprüft werden. Versuchen Sie es erneut.

  • 503UNSUBSCRIBE_UNAVAILABLE

    Dienst für Abmeldelinks vorübergehend nicht verfügbar. Versuchen Sie es später erneut.