Docs
Docs
La API de Warmup permite gestionar mediante programación las cuentas de envío de calentamiento de correo electrónico: añadir y eliminar direcciones de remitente, establecer el nivel de intensidad con el que se calienta cada dirección y consultar estadísticas de entregabilidad.
Todo se sirve mediante HTTPS bajo la ruta base /api/v1/warmup. Las solicitudes y respuestas utilizan JSON, excepto dos endpoints de descarga CSV.
Todas las rutas utilizan guiones. Las variantes con guiones bajos no están registradas y devuelven 404.
ZeroBounce proporciona la URL base para su cuenta:
A lo largo de este documento, la URL base se escribe como {BASE}. Para construir una URL de solicitud completa, agregue la ruta del endpoint al final.
Cada solicitud debe incluir tu clave API del producto en el encabezado API-Key:
Las solicitudes con un cuerpo JSON también deben enviar Content-Type: application/json.
Los ejemplos de este documento asumen estas variables de shell:
Tu clave está vinculada a un único equipo. La API determina el equipo a partir de la clave en cada llamada, por lo que ningún endpoint solicita que proporciones un identificador de equipo. Cuando un esquema todavía contiene un campo team_id, cualquier valor que envíes será reemplazado en el servidor por el equipo al que pertenece la clave.
La API utiliza dos estructuras de error diferentes, y cuál recibes depende del tipo de problema. Conocer esta distinción simplifica considerablemente la gestión de errores.
Esta es la distinción que conviene implementar en tu cliente:
Por ejemplo, {"engagement_rule_id": "two"} devuelve 422, mientras que {"engagement_rule_id": 9} devuelve 400. No esperes una matriz detail en un 400 ni una cadena de error en un 422.
Se utilizan dos nombres para la misma cosa en diferentes endpoints. Ambos hacen referencia a una dirección de remitente que has registrado:
Cuando la dirección aparece en una ruta URL en lugar de una cadena de consulta, codifica la @ en la URL.
Todas las rutas son relativas a {BASE}/api/v1/warmup.
Existen dos modelos de incorporación, seleccionados mediante el campo onboarding_model en POST /sending-accounts.
Tú eres propietario del buzón y de su configuración SMTP. Warmup gestiona el calendario de envío y la interacción.
Campos obligatorios: from_address, onboarding_model, engagement_rule_id (0 a 4).
Una respuesta 200 devuelve onboarding_model: self_managed y recuerda que debes configurar SMTP de tu lado.
Acciones posteriores útiles: POST /test-smtp-configuration para comprobar la conectividad, GET /check-domain-dmarc para verificar los registros del dominio y PUT /engagement-rule para cambiar el ritmo posteriormente.
ZeroBounce configura y realiza los envíos desde el buzón. Tú proporcionas el contexto de la empresa utilizado para generar el contenido de warmup, además de un calendario de envío opcional.
Campos obligatorios: from_address, onboarding_model: zb_managed. Opcionales: email_content, managed_sending. Cualquier engagement_rule_id que envíes se ignora en esta ruta.
Una dirección from-address duplicada devuelve 409.
El bloque managed_sending es de solo escritura. No existe ningún endpoint público para consultarlo o modificarlo después de la creación.
PUT /sending-accounts modifica la regla de interacción, el estado y el indicador de activación automática de una dirección existente.
auto_enable admite null en el esquema, pero en la práctica es obligatorio. Enviar null o no incluir la clave devuelve 400 {"error": "Missing auto_enable parameter"}. Envía siempre un booleano explícito.
auto_enable: true solo se acepta en una cuenta que actualmente no esté activa. Cualquier estado distinto de Paused o Disabled se considera activo:
PUT /smtp-credentials tiene ese nombre por razones históricas. No almacena un host SMTP, nombre de usuario ni contraseña. Lo que hace es reasignar una dirección from-address existente a una nueva, conservando la cuenta y su historial.
Devuelve 200 con un cuerpo vacío. Para comprobar la conectividad SMTP, utiliza POST /test-smtp-configuration (sección 8.3).
Devuelve 204. Esta acción es destructiva y no se puede deshacer.
Una regla de interacción controla cómo los destinatarios interactúan con los correos de warmup de una dirección: con qué frecuencia responden, marcan el mensaje como importante o hacen clic. Cada dirección tiene exactamente una regla.
GET /engagement-rules devuelve el catálogo:
Para cambiar la regla de una dirección:
Devuelve 204. rule_id debe estar entre 0 y 4. -1 se rechaza aquí, porque una regla personalizada se crea mediante los endpoints de la sección 7.2.
Una regla personalizada sustituye la regla estándar por tus propios porcentajes de interacción. Al crearla, la dirección pasa a tener engagement_rule_id: -1.
Crear
Devuelve 200 con can_update: false y remaining_seconds de aproximadamente 604800. Una segunda creación para la misma dirección devuelve 409.
Leer
Codifica la @ en la URL de la ruta.
Actualizar
Mismo cuerpo que en la creación, enviado mediante PUT. Devuelve 200 cuando el período de espera ha expirado, 429 mientras siga activo y 404 con "Use POST to create one" si la dirección todavía no tiene una regla personalizada.
Eliminar
Eliminar una regla personalizada restaura una regla estándar, por lo que la solicitud debe indicar cuál. engagement_rule_id aquí es la regla estándar a la que se volverá, no el identificador de la regla personalizada. Debe ser 1 o superior, por lo que las opciones válidas son de 1 a 4.
Devuelve 200 {"status":"ok","deleted":true}.
El identificador de la regla se comprueba antes de buscar la dirección. Una solicitud en la que ambos sean incorrectos devuelve 400 por la regla, no 404 por la dirección.
Después de una eliminación, se puede crear inmediatamente una nueva regla personalizada para la dirección. Esa creación inicia un nuevo período de espera de 7 días.
Una dirección sin historial todavía devuelve 200, con ceros o listas vacías en lugar de un error.
GET /seeds/download y GET /statistics/download devuelven CSV como un adjunto Content-Disposition. El archivo de seeds es warmup_seeds.csv con las columnas seed,provider.
GET /check-domain-dmarc inspecciona los registros DNS. A pesar del nombre del parámetro, from_address aquí recibe un dominio, no una dirección de correo electrónico, y no se valida como correo electrónico. Un dominio vacío devuelve 400.
Añade &dkim_selector=default para comprobar un selector DKIM específico.
POST /test-smtp-configuration comprueba que un conjunto de credenciales SMTP puede conectarse y entregar un mensaje. No se almacena nada.
Un 200 {"message": "Test email sent."} significa que el servidor SMTP aceptó el mensaje. Un fallo significa que las credenciales o los datos del servidor son incorrectos.
Nueve endpoints están limitados a 100 solicitudes por cada 60 segundos por dirección IP. Superar el límite devuelve 429.
Los demás endpoints actualmente no tienen límite de solicitudes. Configura tu cliente para aplicar backoff ante un 429 de todos modos, ya que los límites podrían ampliarse a más rutas en futuras versiones.
Un 429 en PUT /custom-engagement no es un límite de solicitudes. Es el período de espera de 7 días descrito en la sección 7.2.
Tu clave API limita cada solicitud a un único equipo. Solo puedes consultar y modificar las direcciones from-address que pertenecen a ese equipo. Las solicitudes para una dirección que pertenece a otro equipo devuelven una respuesta de recurso no encontrado en lugar de mostrar datos de otro equipo.
Proporcionar un team_id en el cuerpo de una solicitud no cambia esto. El valor siempre se sobrescribe con el equipo determinado a partir de tu clave.
Para obtener las credenciales de acceso o resolver dudas sobre esta API, contacta con tu gestor de cuenta de ZeroBounce.
