Email

Headers personalizados

Adicione headers personalizados aos seus emails usando o objeto headers na requisição de envio.

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

Restrição de nome:qualquer header fora da lista reservada abaixo precisa começar com X-. Isso é exigido para evitar header injection e proteger campos reservados por RFC.

Headers reservados

Estes headers não precisam do prefixo X-. Para os headers de descadastro, vejaHeaders de descadastro.

  • List-Id

    Identifica a lista de emails à qual o email pertence.

  • X-Report-Abuse

    Uma URL onde os destinatários podem denunciar abuso.

  • Feedback-ID

    Identificador que os provedores de email usam para agrupar relatórios de feedback loop.

  • List-Unsubscribe

    Métodos de descadastro (mailto: e/ou https:).

  • List-Unsubscribe-Post

    Ativa o descadastro com um clique.

Qualquer outro header

Precisa ter o prefixo X-. Qualquer outro é rejeitado antes de o email entrar na fila.

Válido

  • "X-MyCustomHeader": "testcustom0"
  • "X-CUSTOM-X": "testcustom1"

Inválido

  • "MyCustomHeader": "testcustom0"
  • → HEADER_NOT_ALLOWED

Início rápido

import axios from 'axios';

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: {
      'List-Id': 'My List <mylist.yourdomain.com>',
      'X-Report-Abuse': 'https://yourdomain.com/report-abuse',
      'Feedback-ID': 'campaign123:subscriber456:list789:youraccount',
      'List-Unsubscribe':
        '<mailto:unsubscribe@yourdomain.com?subject=unsubscribe>,<https://yourdomain.com/unsubscribe?u=123>',
      'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
      'X-MyCustomHeader': 'testcustom0',
      'X-CUSTOM-X': 'testcustom1',
    },
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } }
);

Resposta

{
  "success": true,
  "message": "Email queued successfully",
  "code": "EMAIL_QUEUED_SUCCESS",
  "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f"
}

Os erros retornam um objeto JSON com error, code e responseTime.

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

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