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.
- 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
SHARED_DOMAIN_REQUIRES_PAID_PLANDiese 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.
- 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.
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.
MARKETING_LIMIT_REACHEDWird 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"
}SHARED_DOMAIN_REQUIRES_PAID_PLANWird 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.
- 400
INVALID_JSONThe body is not {"commands":[...]} or has more than 20 commands.
- 401
MISSING_AUTH_HEADERNo Authorization header was sent.
- 401
INVALID_TOKENThe token is malformed, unknown or revoked.
- 401
TOKEN_EXPIREDThe access token has expired. Call Refresh Token and repeat the request.
- 401
INVALID_REFRESH_TOKENThe refresh token is invalid, expired, revoked or already used. Generate a new token in the dashboard.
- 429
RATE_LIMITEDMore than 15 requests/s or 15 in flight for the same IP + mailbox. Wait the number of seconds in Retry-After.
- 503
AUTH_UNAVAILABLEAuthentication 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.
- CMD
INVALID_ARGSA required argument is missing or invalid.
- CMD
UNKNOWN_COMMANDThe command name does not exist.
- CMD
NOT_FOUNDThe message, thread or folder does not exist for this token.
- CMD
INVALID_CURSORThe cursor is malformed or belongs to another account or folder.
- CMD
ALREADY_EXISTSA folder or label with this name already exists.
- CMD
NOT_IN_TRASHdelete only works on messages in Trash or Spam. Use move to send a message to Trash first.
- CMD
SENDER_NOT_FOUNDThe sender behind the token is not registered.
- CMD
SENDER_NO_DOMAINThe sender behind the token has no domain.
- CMD
NO_CREDITSThe account has fewer email credits than recipients (1 credit per copy).
- CMD
NO_RECIPIENTThe conversation has no recipient to reply to.
- CMD
INVALID_RULEThe rule is not valid. The message says which condition or action and why.
- CMD
LIMITThe mailbox reached the limit (100 rules, 200 templates or 100 labels).
- CMD
INVALID_TOADDRESSThe to address is not a valid email.
- CMD
INVALID_CCADDRESSOne of the cc addresses is not a valid email.
- CMD
INVALID_BCCADDRESSOne of the bcc addresses is not a valid email.
- CMD
INVALID_RECIPIENTThe recipient is missing or not a valid email.
- CMD
RECIPIENT_LIMIT_EXCEEDEDto, cc and bcc together have more than 50 addresses.
- CMD
INVALID_ATTACHMENTAn attachment content is not valid base64.
- CMD
FILE_BLOCKEDA file was blocked by the security scan.
- CMD
ATTACHMENTS_TOO_LARGEThe attachments of the email add up to more than 25 MB, or the mailbox already has 500 MB of uploads waiting to be sent.
- CMD
TOO_MANY_OPEN_COMPOSESThe 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.
- CMD
ATTACHMENT_MISSINGAn 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.
- CMD
ALREADY_SENTThe compose_uid belongs to an email that was already sent.
- CMD
INVALID_TIMEsend_at is missing, less than 1 minute away or more than 1 year away.
- CMD
MISSING_SUBJECTA new email needs a subject.
- CMD
MISSING_TARGETReply and forward need the original email, and it must still exist.
- CMD
DRAFT_NOT_FOUNDThe draft does not exist anymore: it was sent, deleted, or saved again (every save returns a new draft_id).
- CMD
NOT_SCHEDULEDThe email was already sent or canceled.
- CMD
SEND_FAILEDThe send was refused. The email is back in Drafts and the message says why.
- CMD
NO_UNSUBSCRIBEThe email has no List-Unsubscribe header.
- CMD
RECIPIENT_UNSUBSCRIBEDOne or more recipients unsubscribed from this mailbox. `recipients` lists them: remove them or send again with `unsubscribe: false`.
- CMD
PAID_PLAN_REQUIREDMore than one address in `to` needs a paid plan.
- CMD
TOO_MANY_RECIPIENTS`to` has more than 30 addresses.
- CMD
INVALID_AUDIENCEThe audience is not valid: unknown group, a segment of another mailbox or a message this mailbox didn’t send.
- CMD
AUDIENCE_OVER_LIMITThe 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.
- CMD
EMPTY_AUDIENCENobody in this audience right now.
- CMD
BEST_TIME_NEEDS_AUDIENCE`best_time` needs an `audience` and `mode: new`.
- CMD
READ_ONLY_ACCESSThe token or app has Read only access and the command writes. In the attachment upload route it is HTTP 403.
- CMD
INTERNALServer error. The detail is only written to the server log.