Email Validator: Rutas

Run Commands

El punto de entrada para la validación de emails. Envía un comando por solicitud: valida una dirección, hasta 50, o lee tu historial.

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

El mismo sobre que Logs y Contacts, pero con exactamente 1 comando por solicitud: una validación habla con servidores de correo reales y puede tardar unos segundos.

i

Los errores se informan en el resultado del comando, y el estado HTTP sigue siendo 200.

Parámetros del cuerpo

  • commandsobject[]obligatorio

    Exactamente 1 comando.

  • commands[].commandstringobligatorio

    validate_email, validate_emails o list_validations.

  • commands[].argsobjectopcional

    Los argumentos del comando.

  • commands[].idstringopcional

    Tu propio identificador para el resultado. Por defecto, "0".

Inicio 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);

Respuesta

{
  "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 de la respuesta

  • type

    Siempre SUCCESS cuando la solicitud en sí fue aceptada.

  • results[0].command / id / type

    El comando, tu id, y SUCCESS o ERROR.

  • results[0].took_ms

    Cuánto tardó la validación. La mayoría de las direcciones tardan de 1 a 5 segundos.

  • results[0].data

    La salida del comando. Solo está presente cuando type es SUCCESS.

  • results[0].code / message

    El error. Solo está presente cuando type es ERROR.

Autenticación

Usa la API key que creas en el dashboard, en Developers → API Keys, con el scope tools:validate.

  • Authorization

    Envía Authorization: <api key> o Authorization: Bearer <api key>.

  • tools:validate

    Necesario para todos los comandos de esta ruta.

  • Tokens de mailbox

    El token del webmail no funciona aquí. Se rechaza con WRONG_CREDENTIAL_TYPE.

Créditos

  • 1 crédito por dirección

    Cada dirección que validas usa un crédito de validación. La misma dirección dos veces en un comando cuenta una vez.

  • Todo o nada

    Si no tienes suficientes créditos para todo el comando, no se valida nada y no se cobra nada (INSUFFICIENT_CREDITS).

  • Reembolso si falla

    Si fallan los servidores de validación, se devuelven los créditos de ese comando (VALIDATION_FAILED).

  • El historial es gratis

    list_validations lee lo que ya validaste y no cuesta nada.

Timeouts

Una validación consulta al servidor de correo real, así que es más lenta que las otras APIs. Configura el timeout de tu cliente HTTP en al menos 2 minutos para validate_emails.

Errores

Los errores a nivel HTTP devuelven type, code y message. Los errores marcados con CMD vuelven dentro del resultado del comando, con HTTP 200.

  • 400INVALID_JSON

    El cuerpo no es {"commands":[...]} o pesa más de 1 MB.

  • 400INVALID_ARGS

    La solicitud no tiene ningún comando o tiene más de uno. Esta ruta acepta exactamente 1 comando por solicitud.

  • 401MISSING_AUTH_HEADER

    No se envió ningún header Authorization.

  • 401INVALID_API_KEY

    La API key no existe, fue revocada o se desactivó en el dashboard.

  • 401API_KEY_EXPIRED

    La API key superó la fecha de expiración definida en el dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Se envió un token de mailbox. La validación de emails necesita una API key del dashboard.

  • 403IP_NOT_ALLOWED

    La solicitud vino de una IP que no está entre las IPs permitidas de la key.

  • 403ACCOUNT_BLOCKED

    La cuenta está bloqueada.

  • 403MISSING_SCOPE

    La key no tiene `tools:validate`, así que no se puede ejecutar ningún comando.

  • 429RATE_LIMITED

    Más de 75 solicitudes/s o 75 simultáneas para la misma IP + API key. Espera el número de segundos indicado en Retry-After.

  • 503AUTH_UNAVAILABLE

    La autenticación no está disponible temporalmente. Inténtalo de nuevo.

  • CMDUNKNOWN_COMMAND

    El nombre del comando no existe.

  • CMDINTERNAL

    Error del servidor. El detalle solo se escribe en el log del servidor.