Email

Headers de descadastro

Adicione headers List-Unsubscribe aos seus emails para que os destinatários (e provedores como Gmail e Yahoo) possam se descadastrar sem marcar seu email como spam. Isso melhora bastante a entregabilidade em envios em massa e de marketing.

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

Os provedores de email recomendam fortemente (e em alguns casos exigem) List-Unsubscribe em qualquer envio em massa. A falta desse header em envios de alto volume pode prejudicar a chegada na caixa de entrada.

i

Os headers vão no objeto headers da requisição de envio. Para as regras de nome que valem para todos os outros headers, vejaHeaders personalizados.

Headers suportados

  • List-Unsubscribeopcional

    Lista de métodos de descadastro separados por vírgula, entre sinais de menor e maior. Aceita um link mailto: e um https:.

    ex. "<mailto:unsubscribe@yourdomain.com?subject=unsubscribe>,<https://yourdomain.com/unsubscribe?u=123>"

  • List-Unsubscribe-Postopcional

    Ativa o descadastro com um clique do Gmail/Yahoo. Obrigatório se você quer que o botão "Cancelar inscrição" apareça direto na interface da caixa de entrada. Precisa ser exatamente:

    ex. "List-Unsubscribe=One-Click"

  • List-Idopcional

    Identifica a lista de emails à qual este email pertence.

    ex. "My List <mylist.yourdomain.com>"

Link de descadastro automático

Se você não tem seu próprio mecanismo de descadastro, a Sendcorex pode gerar e gerenciar o link de descadastro e o mailto para você. Defina unsubscribe: true na requisição de envio e inclua um dos placeholders suportados no corpo, onde quer que o link seja inserido.

Placeholders suportados

  • [unsubscribe_url]
  • [unsubscribe]
  • [unsub_url]
  • [opt_out_url]

Use qualquer um deles dentro de um href (ou em qualquer lugar do corpo). A Sendcorex o substitui pelo link de descadastro real de cada destinatário antes do envio.

unsubscribe: true, sem mecanismo próprio

{
  "to": "contact@gmail.com",
  "from": "noreply@yourdomain.com",
  "senderName": "My App",
  "subject": "Welcome aboard!",
  "body": "<h1>Welcome!</h1><p>Thanks for signing up.</p><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
  "replyTo": "support@yourdomain.com",
  "unsubscribe": true
}
!

Se unsubscribe: true estiver definido mas nenhum dos placeholders suportados for encontrado no corpo, a requisição falha com MISSING_UNSUBSCRIBE_PLACEHOLDER. Veja aresposta 400.

Lista de contatos

opcional

contact_list não é obrigatório. Ele só controla em qual lista o destinatário é salvo, para rastreamento e organização. Não tem nada a ver com o link de descadastro em si.

Sem contact_list (padrão)

O contato é salvo automaticamente em uma lista padrão chamada "API Contacts". Esse nome não pode ser alterado. Você pode conferi-la a qualquer momento nas suaslistas de contatos.

{
  "to": "contact@gmail.com",
  "from": "noreply@yourdomain.com",
  "subject": "Welcome aboard!",
  "body": "<h1>Welcome!</h1><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
  "unsubscribe": true
}

Com contact_list (nome personalizado)

Se a lista ainda não existir, ela é criada automaticamente. Isso é útil para separar públicos, por exemplo uma lista por campanha ou plataforma.

  • "CRM 2026 - Gmail"
  • "Newsletter - Trial Users"
  • "Support Tickets"
{
  "to": "contact@gmail.com",
  "from": "noreply@yourdomain.com",
  "subject": "Welcome aboard!",
  "body": "<h1>Welcome!</h1><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
  "unsubscribe": true,
  "contact_list": "CRM 2026 - Gmail"
}

Início rápido

import axios from 'axios';

const response = await axios.post(
  'https://mail.sendcorex.com/v3.0/send',
  {
    to: 'contact@gmail.com',
    from: 'noreply@yourdomain.com',
    senderName: 'My App',
    subject: 'Welcome aboard!',
    body: '<h1>Welcome!</h1><p>Thanks for signing up.</p><p><a href="[unsubscribe]">Unsubscribe</a></p>',
    unsubscribe: true,
    contact_list: 'CRM 2026 - Gmail',
    headers: {
      'List-Id': 'My List <mylist.yourdomain.com>',
      'List-Unsubscribe':
        '<mailto:unsubscribe@yourdomain.com?subject=unsubscribe>,<https://yourdomain.com/unsubscribe?u=123>',
      'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
    },
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } }
);

const { id } = response.data;

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 e code.

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