Events and webhooks
Connecting webhooks
Set your webhook URL in your integration settings to receive notifications about new messages, mailbox status and operation results.
Set a separate webhook secret in your integration settings and enable delivery. Use this secret to verify notification signatures; your mail API key cannot be used for this purpose.
Notification Format
Notifications arrive as HTTP POST requests with Content-Type: application/json. event identifies the event type, timestamp is the notification time, and data contains the event-specific fields.
Use data.event_id to identify duplicate deliveries. Store it together with your integration identifier and process each event only once.
{ "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 }}Verification and confirmation
X-Webhook-Signature contains an HMAC-SHA256 signature encoded as lowercase hexadecimal. Calculate it using the original request body bytes and your webhook secret. Verify the signature before processing the event; re-serializing JSON changes the signed bytes.
After verifying the signature and saving the event, return HTTP 200 or 201. Responses 202 and 204 do not acknowledge delivery. Respond within 10 seconds and perform lengthy processing after saving the event.
Notifications may arrive more than once and out of order. Check the current subscription before changing its state. Delivery history is available in your integration settings.
Available events
mailbox.created- The mailbox is created and ready to use.
mailbox.expiring- The end of the paid period for the mailbox is approaching.
mailbox.renewed- The paid period for the mailbox has been extended.
mailbox.suspended- Access to the mailbox is suspended: reading and sending are unavailable.
mailbox.resumed- Access to the mailbox has been restored.
mailbox.deleting_soon- There is one hour left before the unpaid mailbox is deleted.
mailbox.deleted- The mailbox has been deleted.
mailbox.account_changed- The mailbox is linked to another mail account.
mail.message.received- A new incoming message has appeared in the mailbox.
mail.operation.succeeded- The operation was completed successfully. For sending, this means acceptance of the message by the mail server, rather than delivery to the recipient's inbox.
mail.operation.failed- The operation failed.
mail.operation.uncertain- The sending outcome is unknown. Check the operation status before sending again.
Payment reminders: 14, 7, 3, 2, 1 day and one hour before expiration. Renewal cancels outdated reminders that have not yet been sent.