API-Referenz

Fehlercodes

Alle Fehlercodes, die die API zurückgeben kann, mit HTTP-Status und Lösung. Send und Receive nutzen unterschiedliche Fehlerformate.

E-Mail senden

Fehler liefern ein JSON-Objekt mit error, code und responseTime. Siehe E-Mail senden.

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

  • 403SHARED_DOMAIN_REQUIRES_PAID_PLAN

    Diese geteilte Versanddomain ist nur in bezahlten Plänen verfügbar. Die Antwort listet in allowedDomains die geteilten Domains, die du nutzen kannst, sowie upgradeUrl. Nutze eine davon oder deine eigene verifizierte Domain.

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

Limits des Free-Plans

Im Free-Plan sind Marketing und Kaltakquise auf 30 E-Mails pro Tag begrenzt, pro Empfänger gezählt (eine E-Mail an 5 Personen zählt als 5) in einem gleitenden 24-Stunden-Fenster. Transaktionale E-Mails sind nicht betroffen. Über dem Limit wird die Anfrage abgelehnt und nichts wird in die Warteschlange gestellt: sende erneut, wenn das Fenster frei wird, oder führe ein Upgrade durch.

403MARKETING_LIMIT_REACHED

Wird von /v3.0/send zurückgegeben, wenn diese E-Mail das Marketing-Limit des Free-Plans überschreiten würde. used ist, was in den letzten 24 Stunden bereits gezählt wurde, und recipients, wie viele diese E-Mail hinzufügen würde.

{
  "code": "MARKETING_LIMIT_REACHED",
  "error": "Daily marketing limit reached for the free plan (30/30, 2 recipients in this email). Transactional emails still go out.",
  "limit": 30,
  "used": 30,
  "recipients": 2,
  "upgradeUrl": "https://app.sendcorex.com/dashboard/billing"
}
403SHARED_DOMAIN_REQUIRES_PAID_PLAN

Wird zurückgegeben, wenn du einen Absender auf einer geteilten Domain anlegst, die nur in bezahlten Plänen verfügbar ist. allowedDomains listet die geteilten Domains, die dein Plan nutzen kann; deine eigene verifizierte Domain funktioniert immer.

{
  "code": "SHARED_DOMAIN_REQUIRES_PAID_PLAN",
  "error": "This shared domain is available on paid plans. Use inboxtaken.com or your own domain.",
  "allowedDomains": ["inboxtaken.com"],
  "upgradeUrl": "https://app.sendcorex.com/dashboard/billing"
}

Vollständige Regeln: Richtlinie zur akzeptablen Nutzung — Free-Plan

Receive: HTTP-Fehler

Diese lehnen die gesamte Anfrage ab. Der Body ist { "type": "ERROR", "code": "...", "message": "..." }. Bei RATE_LIMITED warten Sie die Sekunden aus dem Retry-After-Header ab.

  • 400INVALID_JSON

    The body is not {"commands":[...]} or has more than 20 commands.

  • 401MISSING_AUTH_HEADER

    No Authorization header was sent.

  • 401INVALID_TOKEN

    The token is malformed, unknown or revoked.

  • 401TOKEN_EXPIRED

    The access token has expired. Call Refresh Token and repeat the request.

  • 401INVALID_REFRESH_TOKEN

    The refresh token is invalid, expired, revoked or already used. Generate a new token in the dashboard.

  • 429RATE_LIMITED

    More than 15 requests/s or 15 in flight for the same IP + mailbox. Wait the number of seconds in Retry-After.

  • 503AUTH_UNAVAILABLE

    Authentication is temporarily unavailable. Try again.

Receive: Befehlsfehler

Diese kommen im Ergebnis des Befehls zurück, mit HTTP 200, sodass ein fehlschlagender Befehl die anderen in derselben Anfrage nicht stoppt. Prüfen Sie results[].type. Siehe Befehle ausführen.

  • CMDINVALID_ARGS

    A required argument is missing or invalid.

  • CMDUNKNOWN_COMMAND

    The command name does not exist.

  • CMDNOT_FOUND

    The message, thread or folder does not exist for this token.

  • CMDINVALID_CURSOR

    The cursor is malformed or belongs to another account or folder.

  • CMDALREADY_EXISTS

    A folder or label with this name already exists.

  • CMDNOT_IN_TRASH

    delete only works on messages in Trash or Spam. Use move to send a message to Trash first.

  • CMDSENDER_NOT_FOUND

    The sender behind the token is not registered.

  • CMDSENDER_NO_DOMAIN

    The sender behind the token has no domain.

  • CMDNO_CREDITS

    The account has fewer email credits than recipients (1 credit per copy).

  • CMDNO_RECIPIENT

    The conversation has no recipient to reply to.

  • CMDINVALID_RULE

    The rule is not valid. The message says which condition or action and why.

  • CMDLIMIT

    The mailbox reached the limit (100 rules, 200 templates or 100 labels).

  • CMDINVALID_TOADDRESS

    The to address is not a valid email.

  • CMDINVALID_CCADDRESS

    One of the cc addresses is not a valid email.

  • CMDINVALID_BCCADDRESS

    One of the bcc addresses is not a valid email.

  • CMDINVALID_RECIPIENT

    The recipient is missing or not a valid email.

  • CMDRECIPIENT_LIMIT_EXCEEDED

    to, cc and bcc together have more than 50 addresses.

  • CMDINVALID_ATTACHMENT

    An attachment content is not valid base64.

  • CMDFILE_BLOCKED

    A file was blocked by the security scan.

  • CMDATTACHMENTS_TOO_LARGE

    The attachments of the email add up to more than 25 MB, or the mailbox already has 500 MB of uploads waiting to be sent.

  • CMDTOO_MANY_OPEN_COMPOSES

    The mailbox has 50 emails with uploads that were not sent yet. Send them, or wait for the unused ones to be deleted after 48 hours.

  • CMDATTACHMENT_MISSING

    An uploaded attachment no longer exists (uploads not sent within 48 hours, and not used by a draft or scheduled email, are deleted). Upload it again.

  • CMDALREADY_SENT

    The compose_uid belongs to an email that was already sent.

  • CMDINVALID_TIME

    send_at is missing, less than 1 minute away or more than 1 year away.

  • CMDMISSING_SUBJECT

    A new email needs a subject.

  • CMDMISSING_TARGET

    Reply and forward need the original email, and it must still exist.

  • CMDDRAFT_NOT_FOUND

    The draft does not exist anymore: it was sent, deleted, or saved again (every save returns a new draft_id).

  • CMDNOT_SCHEDULED

    The email was already sent or canceled.

  • CMDSEND_FAILED

    The send was refused. The email is back in Drafts and the message says why.

  • CMDNO_UNSUBSCRIBE

    The email has no List-Unsubscribe header.

  • CMDRECIPIENT_UNSUBSCRIBED

    One or more recipients unsubscribed from this mailbox. `recipients` lists them: remove them or send again with `unsubscribe: false`.

  • CMDPAID_PLAN_REQUIRED

    More than one address in `to` needs a paid plan.

  • CMDTOO_MANY_RECIPIENTS

    `to` has more than 30 addresses.

  • CMDINVALID_AUDIENCE

    The audience is not valid: unknown group, a segment of another mailbox or a message this mailbox didn’t send.

  • CMDAUDIENCE_OVER_LIMIT

    The audience has more people than you can send to (up to 5,000 per email and your daily limit). `total` and `allowed` say how many.

  • CMDEMPTY_AUDIENCE

    Nobody in this audience right now.

  • CMDBEST_TIME_NEEDS_AUDIENCE

    `best_time` needs an `audience` and `mode: new`.

  • CMDREAD_ONLY_ACCESS

    The token or app has Read only access and the command writes. In the attachment upload route it is HTTP 403.

  • CMDINTERNAL

    Server error. The detail is only written to the server log.