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.

  • 401MISSING_AUTH_HEADER

    Nenhum header Authorization presente.

  • 401INVALID_API_KEY

    A API key é inválida ou foi revogada.

  • 401ACCOUNT_BLOCKED

    A conta foi bloqueada.

  • 401NO_CREDITS_LEFT

    Créditos de email insuficientes para todos os destinatários. Cada endereço em to, cc e bcc usa 1 crédito.

  • 401DOMAIN_NOT_VALIDATED

    Domínio do remetente não verificado.

  • 401LISTED_SPAM_HAUS

    O domínio do remetente está listado no Spamhaus.

  • 401ISP_DOMAIN_BLOCKED

    Não é permitido enviar de domínios conhecidos (gmail.com, outlook.com etc).

  • 401FROM_HEADER_DOMAIN_MISMATCH

    Domínio do header From não autorizado para este remetente.

  • 401USER_NOT_FOUND

    Usuário não encontrado.

  • 401MISSING_USER_PRIVILEGES

    Faltam privilégios de usuário.

  • 401EMAIL_CREDITS_NOT_FOUND

    Erro ao buscar os créditos de email.

  • 401EMAIL_NOT_VALIDATED

    O email da conta ainda não foi verificado.

  • 429CREDENTIAL_TEMPORARILY_BLOCKED

    API key bloqueada temporariamente por violações repetidas da política.

  • 429IP_TEMPORARILY_BLOCKED

    IP da requisição bloqueado temporariamente por violações repetidas da política.

  • 429TOO_MANY_CONCURRENT_CONNECTIONS

    Requisições simultâneas demais deste IP. Tente de novo em instantes.

  • 400INVALID_JSON

    O corpo da requisição não é um JSON válido.

  • 400MISSING_FROM

    O campo from está ausente ou vazio.

  • 400INVALID_FROM_FORMAT

    O campo from precisa ser um endereço de email válido.

  • 400MISSING_SENDERNAME

    O campo senderName está ausente ou vazio.

  • 400INVALID_SENDERNAME_FORMAT

    O campo senderName contém caracteres inválidos.

  • 400MISSING_SUBJECT

    O campo subject está ausente ou vazio.

  • 400MISSING_BODY

    O campo body está ausente ou vazio.

  • 400MISSING_TOADDRESS

    O campo to está ausente ou vazio.

  • 400MISSING_TO

    O campo to está ausente ou vazio.

  • 400INVALID_TOADDRESS

    Um ou mais endereços de destinatário estão malformados.

  • 400TOADDRESS_LIMIT_EXCEEDED

    Mais de 50 destinatários no array to.

  • 400INVALID_CCADDRESS

    Um ou mais endereços de cc estão malformados.

  • 400INVALID_BCCADDRESS

    Um ou mais endereços de bcc estão malformados.

  • 400RECIPIENT_LIMIT_EXCEEDED

    to, cc e bcc juntos têm mais de 50 destinatários únicos.

  • 400INVALID_SCHEDULED_AT

    scheduled_at não é uma data válida ou está no passado.

  • 400INVALID_SENDER_FORMAT

    O formato do email do remetente é inválido.

  • 400HEADER_NOT_ALLOWED

    A chave do header personalizado não está na lista permitida (List-Unsubscribe, List-Id, X-* etc).

  • 400INVALID_HEADER_VALUE

    O valor do header contém caracteres inválidos (CR/LF não são permitidos).

  • 400DANGEROUS_ATTACHMENT

    Um ou mais anexos foram bloqueados por motivos de segurança.

  • 400INVALID_ATTACHMENT

    O conteúdo de um anexo não é base64 válido.

  • 400MISSING_UNSUBSCRIBE_PLACEHOLDER

    unsubscribe é true, mas o body não tem placeholder de descadastro ([unsubscribe_url], [unsubscribe], [unsub_url] ou [opt_out_url]).

  • 403ACCOUNT_RESTRICTED

    A conta está restrita temporariamente.

  • 403DAILY_LIMIT

    Limite diário de envio de emails atingido.

  • 403MARKETING_LIMIT_REACHED

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

  • 403FORBIDDEN_HTML_CONTENT

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

  • 403SPAM_DETECTED

    Conteúdo do email marcado como spam. A resposta inclui o quarantine_id e as instruções de liberação.

  • 403SENDER_NAME_MISMATCH

    Vários nomes de remetente detectados para o mesmo endereço.

  • 403FOLLOWUP_PATTERN_DETECTED

    Conteúdo do email marcado como padrão repetido de follow-up suspeito.

  • 403SCAM_PATTERN_DETECTED

    Conteúdo do email marcado como padrão de golpe.

  • 403SHARED_DOMAIN_REQUIRES_PAID_PLAN

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

  • 403ACCOUNT_SUSPENDED_SPOOFING

    Conta suspensa por tentativas repetidas de falsificação do header From.

  • 409IDEMPOTENCY_IN_PROGRESS

    Uma requisição com a mesma Idempotency-Key ainda está sendo processada. Espere (Retry-After: 1) e repita com a mesma chave.

  • 422IDEMPOTENCY_KEY_REUSED

    Esta Idempotency-Key já foi usada com outro corpo. Use uma chave nova para cada email novo.

  • 500INTERNAL_SERVER_ERROR

    Erro inesperado no servidor. Tente de novo.

  • 500PARSE_ERROR

    Falha ao processar o conteúdo do email (falha no parse MIME).

  • 500PERSIST_FAILED

    Falha ao enfileirar o email (falha ao gravar no banco de dados).

  • 503AUTH_UNAVAILABLE

    Não foi possível validar a API key agora. Tente de novo.

  • 503UNSUBSCRIBE_UNAVAILABLE

    Serviç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.

403MARKETING_LIMIT_REACHED

Retornado 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"
}
403SHARED_DOMAIN_REQUIRES_PAID_PLAN

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

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

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.

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