Enviar email
Envie um email transacional ou de marketing para um ou vários destinatários. Suporta corpo em HTML, anexos, reply-to e headers de marketing.
https://mail.sendcorex.com/v3.0/sendPrecisa enviar para vários destinatários de uma vez? Passe to como array — veja Enviar emails em lote.
Parâmetros do body
tostring | string[]obrigatórioEndereço de email do destinatário ou array com até 50 endereços.
ex.
"user@example.com" or ["a@x.com", "b@x.com"]fromstringobrigatórioEndereço de email do remetente. Precisa pertencer a um domínio verificado na sua conta.
senderNamestringobrigatórioNome exibido na caixa de entrada do destinatário.
subjectstringobrigatórioLinha de assunto do email. HTML não é suportado aqui.
bodystringobrigatórioConteúdo HTML do corpo do email.
replyTostringopcionalEndereço de resposta (reply-to). Se omitido, usa o endereço do remetente.
transactionalbooleanopcionalDefina true para marcar como transacional. O padrão é false.
attachmentsobject[]opcionalArray de objetos de anexo. Veja Enviar anexos para todos os detalhes.
retryRateLimitedintegeropcionalQuantos ciclos de 30 minutos continuar tentando quando o provedor aplica rate limit (0–24, padrão 25). Veja Opções de entrega para todos os detalhes.
retryUnavailableintegeropcionalQuantas vezes tentar de novo após um erro temporário (0–30). Use com retryUnavailableSeconds (10–3600). Veja Opções de entrega para todos os detalhes.
ignoreHardBouncebooleanopcionalEnvia mesmo que o endereço tenha dado hard bounce nos últimos 90 dias. O padrão é false. Veja Opções de entrega para todos os detalhes.
Início rápido
import axios from 'axios';
const response = 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: { Authorization: process.env.SENDCOREX_API_KEY },
}
);
const { id, ids, recipients } = response.data;Resposta
{
"success": true,
"message": "Email queued successfully",
"code": "EMAIL_QUEUED_SUCCESS",
"id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
"ids": [
{ "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f", "recipient": "user@example.com" }
],
"recipients": 1,
"scheduledAt": null
}Requisições idempotentes
Envie o cabeçalho Idempotency-Key com qualquer valor único (recomendamos um UUID v4) para repetir o POST /v3.0/send com segurança. Se a conexão cair ou der timeout, repita com a mesma chave e o mesmo corpo: devolvemos a resposta original (mesmo id do email) e o email não é enviado duas vezes.
POST /v3.0/send
Authorization: Bearer <api_key>
Idempotency-Key: 3f1c9a52-6b1e-4f0e-9c2a-8d7e5b4a1f00
Content-Type: application/jsonAs chaves valem por 24 horas e são exclusivas da sua conta.
Caracteres permitidos: letras, números,
_ - : .(1–255 caracteres).Uma resposta repetida vem com o cabeçalho
Idempotent-Replayed: true.Use uma chave nova para cada email novo. Reusar uma chave com outro corpo retorna
422 IDEMPOTENCY_KEY_REUSED.Se a primeira requisição ainda está sendo processada, você recebe
409 IDEMPOTENCY_IN_PROGRESScomRetry-After: 1. Espere e repita com a mesma chave.Erros do servidor (
5xx) e limites de taxa (429) não ficam guardados: repetir com a mesma chave envia normalmente.Sem o cabeçalho, o endpoint funciona como antes.
Retry recomendado: em erro de rede, timeout, 409, 429 ou 5xx, repita com a mesma chave usando backoff exponencial (1 s, 2 s, 4 s…, até 5 tentativas).
Exemplo: chave UUID + retry com backoff
import { randomUUID } from 'node:crypto';
const RETRY_STATUS = new Set([409, 429, 500, 502, 503, 504]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function sendEmail(email) {
const key = randomUUID(); // one key per email, reused on every retry
const body = JSON.stringify(email); // same body on every retry
for (let attempt = 1; attempt <= 5; attempt++) {
try {
const res = await fetch('https://mail.sendcorex.com/v3.0/send', {
method: 'POST',
headers: {
Authorization: process.env.SENDCOREX_API_KEY,
'Idempotency-Key': key,
'Content-Type': 'application/json',
},
body,
signal: AbortSignal.timeout(15_000),
});
if (!RETRY_STATUS.has(res.status)) {
const data = await res.json();
if (!res.ok) throw new Error(data.code || 'SEND_FAILED');
// Idempotent-Replayed: true → this is the original response (not sent twice)
return { ...data, replayed: res.headers.get('Idempotent-Replayed') === 'true' };
}
if (attempt === 5) throw new Error('HTTP ' + res.status);
const retryAfter = Number(res.headers.get('Retry-After')) * 1000;
await sleep(retryAfter || 1000 * 2 ** (attempt - 1));
} catch (err) {
// network error or timeout: retry with the same key
if (err.message?.startsWith('HTTP ') || attempt === 5 || (err.name !== 'TypeError' && err.name !== 'TimeoutError')) throw err;
await sleep(1000 * 2 ** (attempt - 1));
}
}
}
const result = await sendEmail({
to: 'user@example.com',
from: 'noreply@yourdomain.com',
senderName: 'My App',
subject: 'Your receipt',
body: '<p>Thanks for your order.</p>',
});
console.log(result.id, result.replayed);Minhas mensagens são marcadas como spam
Toda mensagem passa pelo nosso filtro anti-spam. Quando uma é marcada, a requisição retorna 403 com o código SPAM_DETECTED e o email fica retido em quarentena.
Marcado como spam
{
"error": "Email content flagged as spam.",
"code": "SPAM_DETECTED",
"detectionId": "9c1e5a7d-2b4f-4e8a-a6d3-0f1b2c3d4e5f",
"quarantine_id": "qtn_3f2a1b4c8e9d4f7a",
"release_instructions": "POST /v3.0/quarantine/release with { quarantine_id }",
"expires_in": "3 hours"
}codeSempre SPAM_DETECTED nesta resposta.
detectionIdIdentificador desta detecção. Inclua-o ao falar com o suporte.
quarantine_idPasse-o para /quarantine/release para enviar o email após a revisão.
release_instructionsComo liberar o email.
expires_inPor quanto tempo o registro de quarentena é mantido antes de expirar.
Um email em quarentena não é entregue. Use /quarantine/release para enviá-lo após a revisão. O registro de quarentena expira após 3 horas.
Se quarantine_id, release_instructions e expires_in vierem como null, o email foi bloqueado sem registro de quarentena. Ele não pode ser liberado: corrija o conteúdo e envie novamente.
Os erros retornam um objeto JSON com error, code e responseTime.
- 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.