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.
https://mail.sendcorex.com/v3.0/sendOs 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.
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-UnsubscribeopcionalLista 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-PostopcionalAtiva 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-IdopcionalIdentifica 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
opcionalcontact_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.
- 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
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.