Email

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.

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

Precisa 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ório

    Endereç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ório

    Endereço de email do remetente. Precisa pertencer a um domínio verificado na sua conta.

  • senderNamestringobrigatório

    Nome exibido na caixa de entrada do destinatário.

  • subjectstringobrigatório

    Linha de assunto do email. HTML não é suportado aqui.

  • bodystringobrigatório

    Conteúdo HTML do corpo do email.

  • replyTostringopcional

    Endereço de resposta (reply-to). Se omitido, usa o endereço do remetente.

  • transactionalbooleanopcional

    Defina true para marcar como transacional. O padrão é false.

  • attachmentsobject[]opcional

    Array de objetos de anexo. Veja Enviar anexos para todos os detalhes.

  • retryRateLimitedintegeropcional

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

  • retryUnavailableintegeropcional

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

  • ignoreHardBouncebooleanopcional

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

HTTP
POST /v3.0/send
Authorization: Bearer <api_key>
Idempotency-Key: 3f1c9a52-6b1e-4f0e-9c2a-8d7e5b4a1f00
Content-Type: application/json
  • As 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_PROGRESS com Retry-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.

403

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"
}
  • code

    Sempre SPAM_DETECTED nesta resposta.

  • detectionId

    Identificador desta detecção. Inclua-o ao falar com o suporte.

  • quarantine_id

    Passe-o para /quarantine/release para enviar o email após a revisão.

  • release_instructions

    Como liberar o email.

  • expires_in

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

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