Cómo personalizar la API en tiempo real
Cómo crear una API personalizada para validar direcciones de correo electrónico en formularios, aplicaciones o servicios web
Priscila G.
Última actualización hace 17 días
Puedes personalizar e instalar la API de verificación de correo electrónico de SafetyMails con total flexibilidad, utilizando el lenguaje de programación que prefieras. Con solo unas pocas líneas de código y tus claves de acceso, puedes integrar la verificación en tiempo real directamente en páginas de destino, formularios, aplicaciones o sistemas de punto de venta (POS).
La API responde al instante a las consultas, proporcionándote los datos que necesitas para bloquear direcciones de correo electrónico no válidas, reducir el fraude y proteger tus registros desde el primer contacto.
📌Nuestro equipo está a tu disposición para ayudarte a configurar el código. Solo tienes que hacer clic en el enlace que aparece en el horario de asistencia para hablar con nuestros expertos.
1. Inicia sesión en tu cuenta y activa los créditos
Debes disponer de una suscripción de crédito activa para utilizar la API de verificación de correo electrónico. Consulta aquí los paquetes de verificación de correo electrónico disponibles.
2. Acceder a la API en tiempo real
- En el menú superior de la plataforma, haz clic en «API en tiempo real».
- Haz clic en «Añadir una nueva fuente»
- A continuación, selecciona «Para desarrolladores».
3. Registrar el origen del cheque
Una vez registrado el origen, el sistema generará automáticamente los siguientes datos:
- Clave API
- Ticket de origen
Estas claves se utilizarán en tu código de integración de la API.
| Example of source ticket and API key |
| APIKey 55a89975b74************75217b0a2eae840bd |
| Ticket Origem b440e8d30f068************3d08b84afe2fe50 |
4. Autenticación mediante HMAC
| Example |
| Sf-Hmac: afc5382171c3745890b56********************4aa43506326b4e1fc993cb |
5. Sintaxis para realizar consultas a la API de verificación de correo electrónico
Para realizar llamadas a la API de verificación en tiempo real de SafetyMails, debes configurar correctamente la URL y enviar el correo electrónico mediante el método POST. Así es como funciona:
Genera el código de ticket con el algoritmo SHA1:
CODE_TICKET = SHA1(<TICKET_ORIGEM>)
Configura la URL de la solicitud con este formato:
https://<TICKET_ORIGEM>.safetymails.com/api/<CODE_TICKET>
Envía la solicitud incluyendo el campo de correo electrónico en el cuerpo de la solicitud POST.
Genera el código de ticket con el algoritmo SHA1:
CODE_TICKET = SHA1(<TICKET_ORIGEM>)
Configura la URL de la solicitud con este formato:
https://<TICKET_ORIGEM>.safetymails.com/api/<CODE_TICKET>
Envía la solicitud incluyendo el campo de correo electrónico en el cuerpo de la solicitud POST.
📌 Importante: El correo electrónico debe enviarse con el nombre del campo exactamente como «email», y debe figurar en el encabezado la autenticación mediante Sf-Hmac.
Ejemplo de código JavaScript
Código de ejemplo en PHP
Código de ejemplo en Python
Ejemplo de código en Java
Código de ejemplo en Go
8. Estructura y significado de las respuestas de la API
Tras cada solicitud, la API de SafetyMails devuelve una respuesta en formato JSON, que indica si la verificación se ha realizado correctamente, el estado de la dirección de correo electrónico consultada y cuántos créditos quedan disponibles en la cuenta.
Esta información es esencial para identificar rápidamente si la dirección de correo electrónico es válida, no válida, de riesgo o desconocida, así como para señalar posibles problemas técnicos u operativos.
A continuación, puedes consultar los principales campos que devuelve la API:
Esta información es esencial para identificar rápidamente si la dirección de correo electrónico es válida, no válida, de riesgo o desconocida, así como para señalar posibles problemas técnicos u operativos.
A continuación, puedes consultar los principales campos que devuelve la API:
| Field | ¿O qué significa eso? |
| Success | Devuelve un valor de tipo bool (true o false). Indica si la solicitud se ha ejecutado correctamente. Si devuelve false, significa que la consulta no se ha llevado a cabo y que pueden haber errores tales como: clave de API incorrecta, ticket no válido o inactivo, parámetros mal formados, límite de solicitudes superado o falta de créditos. |
| DomainStatus | Estado del dominio de correo electrónico consultado. |
| Status | Resultado de la validación del correo electrónico, si se ha realizado con éxito. El estado puede ser: válido, basado en roles, baja capacidad de entrega, desechable, incierto, correo basura, no válido, dominio no válido, error de sintaxis y pendiente. |
| Se ha consultado el correo electrónico. | |
| Limited | Esto te indica si el correo electrónico que estás viendo procede de un proveedor con capacidad limitada, es decir, uno que recibe un número limitado de solicitudes. |
| Public | Te indica si el correo electrónico que estás consultando procede de un dominio «corporativo» (dominios privados y/o dominios con normas propias para la recepción de correos electrónicos) o de un dominio de «proveedor de correo electrónico» (dominios con normas públicas para la recepción de correos electrónicos). |
| Advice | Se trata de una clasificación propuesta por SafetyMails para indicar el estado del correo electrónico consultado (válido, no válido, de riesgo o desconocido) con el fin de facilitar el análisis. |
| Balance | Número de créditos de consulta disponibles en tu cuenta. |
| Msg | Devuelve el mensaje de error correspondiente al fallo de la llamada (solo cuando la llamada falla). |
Ejemplo de un resultado correcto (JSON)
Ejemplo en caso de error en una consulta (JSON)
9. Mensajes de error devueltos por la API de verificación por correo electrónico
Los mensajes de error que se muestran a continuación solo aparecerán cuando el campo «Success» tenga el valor «false» en la respuesta de la API. En estos casos, la consulta no se ha realizado correctamente y el campo «Msg» te indicará el motivo del error.
Estos errores suelen estar relacionados con problemas de autenticación, parámetros incorrectos, falta de créditos o superación de los límites.
| HTTP CODE | ERRO | DESCRIPTION |
| 400 | Invalid parameters | Teclas de acceso incorrectas o inexistentes. |
| 401 | Invalid API Key | Teclas de acceso incorrectas o inexistentes. |
| 406 | Invalid or inactive Source Ticket | Estás intentando realizar consultas para un origen de API inactivo. Ve a tu panel de control y activa el origen correctamente. |
| 403 | Origin different from registered (%s)<>(%s) | Estás intentando realizar consultas para un origen de API distinto al registrado en tu cuenta. Comprueba el origen e inténtalo de nuevo. |
| 429 | Limit of queries per hour or minute or daily exceeded - Contact Support | Safetymails protege tu formulario contra el uso indebido permitiéndote limitar el número de consultas procedentes de una misma dirección IP. Además, todos los planes tienen límites en el número de consultas por hora y por minuto, lo que te protege de errores que puedan provocar bucles. Si deseas realizar más consultas de las previstas, ponte en contacto con el servicio de asistencia (support@safetymails.com). |
| 402 | No credits for research | Tu cuenta no dispone de créditos suficientes para realizar la consulta. Tienes que comprar créditos. |
📌 Consejo: Comprueba siempre el campo «Msg» en la respuesta JSON para conocer el motivo exacto del error.
Si necesitas más ayuda para configurar tu API, ponte en contacto con nuestro equipo de asistencia:
📧 support@safetymails.com