Email Validator: Rotas

Run Commands

O ponto de entrada para validação de email. Envie um comando por requisição: valide um endereço, até 50, ou leia seu histórico.

POSThttps://g.sendcorex.com/v1/tool/validate
i

Mesmo envelope de Logs e Contacts, mas com exatamente 1 comando por requisição: uma validação conversa com servidores de email reais e pode levar alguns segundos.

i

Os erros são reportados no resultado do comando, e o status HTTP continua 200.

Parâmetros do corpo

  • commandsobject[]obrigatório

    Exatamente 1 comando.

  • commands[].commandstringobrigatório

    validate_email, validate_emails ou list_validations.

  • commands[].argsobjectopcional

    Os argumentos do comando.

  • commands[].idstringopcional

    Seu próprio identificador para o resultado. Padrão: "0".

Início rápido

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/tool/validate',
  {
    commands: [
      {
        command: "validate_email",
        args: {
          email: "ana@acme.com"
        }
      }
    ]
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);

const [result] = response.data.results;
if (result.type !== 'SUCCESS') throw new Error(`${result.code}: ${result.message}`);
console.log(result.data);

Resposta

{
  "type": "SUCCESS",
  "results": [
    {
      "command": "validate_email",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 1840,
      "data": {
        "email": "ana@acme.com",
        "valid": true,
        "checks": [
          {
            "check": "Format Validation",
            "status": "Passed",
            "details": "Valid email format"
          },
          {
            "check": "Local Part Validation",
            "status": "Passed",
            "details": "Local part is RFC compliant"
          },
          {
            "check": "Role-based Email Check",
            "status": "Passed",
            "details": "Not a role-based address"
          },
          {
            "check": "No-reply Email Check",
            "status": "Passed",
            "details": "Not a no-reply address"
          },
          {
            "check": "Temporary Email Check",
            "status": "Passed",
            "details": "Not a temporary email"
          },
          {
            "check": "Misspelled Domain Check",
            "status": "Passed",
            "details": "Correct"
          },
          {
            "check": "Spam Trap Check",
            "status": "Passed",
            "details": "Not a spam trap"
          },
          {
            "check": "Provider Type",
            "status": "Passed",
            "details": "Corporate or custom domain"
          },
          {
            "check": "Domain Validation",
            "status": "Passed",
            "details": "Domain is valid and has MX records"
          },
          {
            "check": "Null MX Check",
            "status": "Passed",
            "details": "Domain accepts email"
          },
          {
            "check": "Email Provider Detection",
            "status": "Passed",
            "details": "Domain is hosted on a known provider: Google Workspace",
            "providerId": 1,
            "providerName": "Google Workspace"
          },
          {
            "check": "Email Deliverability",
            "status": "Passed",
            "details": "Mailbox exists",
            "fullResponse": "250 2.1.5 OK"
          },
          {
            "check": "Catch-all Mail Exchanger Check",
            "status": "Passed",
            "details": "Mail exchanger correctly rejects nonexistent addresses"
          }
        ]
      }
    }
  ]
}

Campos da resposta

  • type

    Sempre SUCCESS quando a requisição em si foi aceita.

  • results[0].command / id / type

    O comando, seu id, e SUCCESS ou ERROR.

  • results[0].took_ms

    Quanto tempo a validação levou. A maioria dos endereços leva de 1 a 5 segundos.

  • results[0].data

    A saída do comando. Só aparece quando type é SUCCESS.

  • results[0].code / message

    O erro. Só aparece quando type é ERROR.

Autenticação

Use a API key que você cria no dashboard, em Developers → API Keys, com o escopo tools:validate.

  • Authorization

    Envie Authorization: <api key> ou Authorization: Bearer <api key>.

  • tools:validate

    Necessário para todos os comandos desta rota.

  • Tokens de mailbox

    O token do webmail não funciona aqui. Ele é rejeitado com WRONG_CREDENTIAL_TYPE.

Créditos

  • 1 crédito por endereço

    Cada endereço que você valida usa um crédito de validação. O mesmo endereço duas vezes em um comando conta uma vez.

  • Tudo ou nada

    Se você não tiver créditos suficientes para o comando inteiro, nada é validado e nada é cobrado (INSUFFICIENT_CREDITS).

  • Reembolso em caso de falha

    Se os servidores de validação falharem, os créditos daquele comando são devolvidos (VALIDATION_FAILED).

  • O histórico é grátis

    list_validations lê o que você já validou e não custa nada.

Timeouts

Uma validação consulta o servidor de email real, então é mais lenta que as outras APIs. Configure o timeout do seu cliente HTTP para pelo menos 2 minutos em validate_emails.

Erros

Erros no nível HTTP retornam type, code e message. Erros marcados com CMD voltam dentro do resultado do comando, com HTTP 200.

  • 400INVALID_JSON

    O corpo não é {"commands":[...]} ou tem mais de 1 MB.

  • 400INVALID_ARGS

    A requisição não tem comando ou tem mais de um. Esta rota aceita exatamente 1 comando por requisição.

  • 401MISSING_AUTH_HEADER

    Nenhum header Authorization foi enviado.

  • 401INVALID_API_KEY

    A API key não existe, foi revogada ou foi desativada no dashboard.

  • 401API_KEY_EXPIRED

    A API key passou da data de expiração definida no dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Foi enviado um token de mailbox. A validação de email precisa de uma API key do dashboard.

  • 403IP_NOT_ALLOWED

    A requisição veio de um IP que não está nos IPs permitidos da key.

  • 403ACCOUNT_BLOCKED

    A conta está bloqueada.

  • 403MISSING_SCOPE

    A key não tem `tools:validate`, então nenhum comando pode rodar.

  • 429RATE_LIMITED

    Mais de 75 requisições/s ou 75 simultâneas para o mesmo IP + API key. Aguarde o número de segundos em Retry-After.

  • 503AUTH_UNAVAILABLE

    A autenticação está temporariamente indisponível. Tente de novo.

  • CMDUNKNOWN_COMMAND

    O nome do comando não existe.

  • CMDINTERNAL

    Erro no servidor. O detalhe só é gravado no log do servidor.