Referência da API
Códigos de erro
Todos os códigos de erro que a API pode retornar, com o status HTTP e o que fazer. Envio e recebimento usam formatos de erro diferentes.
Enviar email
Os erros retornam um objeto JSON com error, code e responseTime. Veja Enviar email.
- 401
MISSING_AUTH_HEADERNenhum header Authorization presente.
- 401
INVALID_API_KEYA API key é inválida ou foi revogada.
- 401
ACCOUNT_BLOCKEDA conta foi bloqueada.
- 401
NO_CREDITS_LEFTCréditos de email insuficientes para todos os destinatários. Cada endereço em to, cc e bcc usa 1 crédito.
- 401
DOMAIN_NOT_VALIDATEDDomínio do remetente não verificado.
- 401
LISTED_SPAM_HAUSO domínio do remetente está listado no Spamhaus.
- 401
ISP_DOMAIN_BLOCKEDNão é permitido enviar de domínios conhecidos (gmail.com, outlook.com etc).
- 401
FROM_HEADER_DOMAIN_MISMATCHDomínio do header From não autorizado para este remetente.
- 401
USER_NOT_FOUNDUsuário não encontrado.
- 401
MISSING_USER_PRIVILEGESFaltam privilégios de usuário.
- 401
EMAIL_CREDITS_NOT_FOUNDErro ao buscar os créditos de email.
- 401
EMAIL_NOT_VALIDATEDO email da conta ainda não foi verificado.
- 429
CREDENTIAL_TEMPORARILY_BLOCKEDAPI key bloqueada temporariamente por violações repetidas da política.
- 429
IP_TEMPORARILY_BLOCKEDIP da requisição bloqueado temporariamente por violações repetidas da política.
- 429
TOO_MANY_CONCURRENT_CONNECTIONSRequisições simultâneas demais deste IP. Tente de novo em instantes.
- 400
INVALID_JSONO corpo da requisição não é um JSON válido.
- 400
MISSING_FROMO campo from está ausente ou vazio.
- 400
INVALID_FROM_FORMATO campo from precisa ser um endereço de email válido.
- 400
MISSING_SENDERNAMEO campo senderName está ausente ou vazio.
- 400
INVALID_SENDERNAME_FORMATO campo senderName contém caracteres inválidos.
- 400
MISSING_SUBJECTO campo subject está ausente ou vazio.
- 400
MISSING_BODYO campo body está ausente ou vazio.
- 400
MISSING_TOADDRESSO campo to está ausente ou vazio.
- 400
MISSING_TOO campo to está ausente ou vazio.
- 400
INVALID_TOADDRESSUm ou mais endereços de destinatário estão malformados.
- 400
TOADDRESS_LIMIT_EXCEEDEDMais de 50 destinatários no array to.
- 400
INVALID_CCADDRESSUm ou mais endereços de cc estão malformados.
- 400
INVALID_BCCADDRESSUm ou mais endereços de bcc estão malformados.
- 400
RECIPIENT_LIMIT_EXCEEDEDto, cc e bcc juntos têm mais de 50 destinatários únicos.
- 400
INVALID_SCHEDULED_ATscheduled_at não é uma data válida ou está no passado.
- 400
INVALID_SENDER_FORMATO formato do email do remetente é inválido.
- 400
HEADER_NOT_ALLOWEDA chave do header personalizado não está na lista permitida (List-Unsubscribe, List-Id, X-* etc).
- 400
INVALID_HEADER_VALUEO valor do header contém caracteres inválidos (CR/LF não são permitidos).
- 400
DANGEROUS_ATTACHMENTUm ou mais anexos foram bloqueados por motivos de segurança.
- 400
INVALID_ATTACHMENTO conteúdo de um anexo não é base64 válido.
- 400
MISSING_UNSUBSCRIBE_PLACEHOLDERunsubscribe é true, mas o body não tem placeholder de descadastro ([unsubscribe_url], [unsubscribe], [unsub_url] ou [opt_out_url]).
- 403
ACCOUNT_RESTRICTEDA conta está restrita temporariamente.
- 403
DAILY_LIMITLimite diário de envio de emails atingido.
- 403
MARKETING_LIMIT_REACHEDLimite diário de marketing do plano free atingido: 30 emails de marketing ou cold outreach por dia, contados por destinatário numa janela móvel de 24 horas. A resposta traz limit, used, recipients e upgradeUrl. Emails transacionais continuam saindo; nada fica na fila.
- 403
FORBIDDEN_HTML_CONTENTO HTML contém conteúdo ativo não permitido em emails (script, iframe, form, input, button, embed, object, svg, handlers on*, links javascript:, meta refresh…). A resposta lista o que foi encontrado. Use um <a> estilizado em vez de botões ou formulários.
- 403
SPAM_DETECTEDConteúdo do email marcado como spam. A resposta inclui o quarantine_id e as instruções de liberação.
- 403
SENDER_NAME_MISMATCHVários nomes de remetente detectados para o mesmo endereço.
- 403
FOLLOWUP_PATTERN_DETECTEDConteúdo do email marcado como padrão repetido de follow-up suspeito.
- 403
SCAM_PATTERN_DETECTEDConteúdo do email marcado como padrão de golpe.
- 403
SHARED_DOMAIN_REQUIRES_PAID_PLANEste domínio de envio compartilhado está disponível só nos planos pagos. A resposta lista em allowedDomains os domínios compartilhados que você pode usar, além de upgradeUrl. Use um deles ou o seu próprio domínio verificado.
- 403
ACCOUNT_SUSPENDED_SPOOFINGConta suspensa por tentativas repetidas de falsificação do header From.
- 409
IDEMPOTENCY_IN_PROGRESSUma requisição com a mesma Idempotency-Key ainda está sendo processada. Espere (Retry-After: 1) e repita com a mesma chave.
- 422
IDEMPOTENCY_KEY_REUSEDEsta Idempotency-Key já foi usada com outro corpo. Use uma chave nova para cada email novo.
- 500
INTERNAL_SERVER_ERRORErro inesperado no servidor. Tente de novo.
- 500
PARSE_ERRORFalha ao processar o conteúdo do email (falha no parse MIME).
- 500
PERSIST_FAILEDFalha ao enfileirar o email (falha ao gravar no banco de dados).
- 503
AUTH_UNAVAILABLENão foi possível validar a API key agora. Tente de novo.
- 503
UNSUBSCRIBE_UNAVAILABLEServiço de link de descadastro temporariamente indisponível. Tente mais tarde.
Limites do plano free
No plano free, marketing e cold outreach ficam limitados a 30 emails por dia, contados por destinatário (um email para 5 pessoas conta 5) numa janela móvel de 24 horas. Emails transacionais não são afetados. Acima do limite a requisição é recusada e nada fica na fila: envie de novo quando a janela liberar, ou faça upgrade.
MARKETING_LIMIT_REACHEDRetornado pelo /v3.0/send quando este email passaria do limite de marketing do plano free. used é o que já foi contado nas últimas 24 horas e recipients é quantos este email somaria.
{
"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_PLANRetornado ao criar um remetente num domínio compartilhado disponível só nos planos pagos. allowedDomains lista os domínios compartilhados que o seu plano pode usar; o seu próprio domínio verificado sempre funciona.
{
"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"
}Regras completas: Política de Uso Aceitável — Plano free
Recebimento: erros HTTP
Estes rejeitam a requisição inteira. O body é { "type": "ERROR", "code": "...", "message": "..." }. Em RATE_LIMITED, espere os segundos indicados no header Retry-After.
- 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.
Recebimento: erros de comando
Estes voltam dentro do resultado do comando, com HTTP 200, então um comando com falha não interrompe os outros na mesma requisição. Verifique results[].type. Veja Executar comandos.
- 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.