Eventos y webhooks
Conectando webhooks
Especifique la dirección para recibir webhooks en su configuración de integración. Recibirá notificaciones sobre nuevas cartas, el estado de los buzones y los resultados de las operaciones.
En la configuración de integración, establezca un secreto de webhook independiente y habilite la entrega. Este secreto se utiliza para verificar las firmas de notificaciones; mail API-key no es adecuado para esto.
Formato de notificación
La notificación llega HTTP POST- solicitud con Content-Type: application/json. El campo event contiene el tipo de evento, timestamp - hora de notificación, data - datos del evento. La composición de data depende del evento.
El identificador data.event_id permite reconocer el reenvío. Guárdelo junto con su ID de integración y procese un evento solo una vez.
{ "event": "mail.message.received", "timestamp": "2026-11-01T12:00:00Z", "data": { "event_id": "00000000-0000-4000-8000-000000000001", "created_at": "2026-11-01T12:00:00Z", "mailbox_id": 42, "folder": "INBOX", "uidvalidity": 123456, "uid": 120 }}Verificación y confirmación
El encabezado X-Webhook-Signature contiene HMAC-SHA256 en notación hexadecimal en minúsculas. Calcule la firma a partir de los bytes originales del cuerpo de la solicitud y el secreto del webhook. Verificar la firma antes de procesar los datos; volver a serializar JSON cambiará los bytes que se firman.
Después de verificar la firma y guardar el evento, devuelva HTTP 200 o 201. Las respuestas 202 y 204 no acusan recibo. Responda dentro de los 10 segundos; Realice un procesamiento prolongado después de guardar el evento.
Las notificaciones pueden llegar repetidas veces y desordenadas. Antes de cambiar el estado de la suscripción, verifique sus detalles actuales. El historial de entrega está disponible en la configuración de integración.
que eventos ocurren
mailbox.created- La caja está creada y lista para usar.
mailbox.expiring- Se acerca el final del periodo de pago de la caja.
mailbox.renewed- Se ha ampliado el plazo de pago de la caja.
mailbox.suspended- El acceso al buzón está suspendido: la lectura y el envío no están disponibles.
mailbox.resumed- Se ha restablecido el acceso al buzón.
mailbox.deleting_soon- Queda una hora para que se borre la casilla no pagada.
mailbox.deleted- El cuadro ha sido eliminado.
mailbox.account_changed- El buzón está vinculado a otra cuenta de correo.
mail.message.received- Ha aparecido una nueva carta entrante en el buzón.
mail.operation.succeeded- La operación se completó con éxito. Para el envío, esto significa la aceptación de la carta por parte del servidor de correo, en lugar de su entrega en la bandeja de entrada del destinatario.
mail.operation.failed- La operación fracasó.
mail.operation.uncertain- Se desconoce el resultado del envío. Por favor verifique el estado antes de reenviar.
Recordatorios de pago: 14, 7, 3, 2, 1 día y una hora antes del vencimiento. La renovación cancela los recordatorios obsoletos que aún no se han enviado.