Transactional webhooks

Webhooks let your application receive real-time notifications when something happens to a transactional email after it is sent. Instead of polling the API to check delivery status, Flexmail sends an HTTP POST request to your endpoint the moment an event occurs.

This is particularly valuable for transactional email: you can take immediate action when a password reset bounces, when an order confirmation is delivered, or when a recipient reports a message as spam.

Webhook events

Flexmail sends a webhook notification for each of the following events:

• Sent — the message was accepted by Flexmail and handed off to the receiving mail server.
• Rejected — the message was rejected by Flexmail and was not sent
• Delivered — the receiving mail server confirmed accepting the message for further processing
• Bounced — delivery failed. Hard bounces indicate a permanent problem (address does not exist); soft bounces indicate a temporary issue (mailbox full, server unavailable).
• Opened — the recipient opened the message.
• Clicked — the recipient clicked a tracked link in the message.

Setting up a webhook endpoint

Your webhook endpoint is a URL on your server that accepts HTTP POST requests and returns a 200 response to acknowledge receipt.

Requirements for your endpoint

• Accepts HTTP POST requests.
• Is publicly accessible over HTTPS.
• Returns a 2xx  HTTP status code within a reasonable timeout to confirm receipt.
• Processes the payload asynchronously if your handling logic is slow — respond immediately and process in the background to avoid timeouts.

Registering your endpoint in Flexmail

Webhook endpoint configuration is done through the API. The full registration process and available options are documented in the API documentation at email-api.flexmail.eu/documentation, under the Webhooks section.

Webhook payload

Each webhook notification is an HTTP POST request with a JSON body. The payload contains the event type, a timestamp, the message ID, and the recipient's email address. Depending on the event, additional fields are included — for example, a bounce event includes the bounce type and reason, and a click event includes the URL that was clicked.

A typical payload looks like this:

{
	"event": "delivered",
	"timestamp": "2024-11-15T09:32:00Z",
	"messageId": "abc123",
	"recipient": "customer@example.com"
}

The full payload specification for each event type is in the API documentation: email-api.flexmail.eu/documentation/webhooks

What to do with webhook events

Bounces

When you receive a hard bounce event, flag that email address in your system. Stop sending to it and investigate whether the address was entered correctly. Continuing to send to hard-bounced addresses damages your sender reputation.

Spam complaints

When a recipient marks a transactional email as spam, suppress that address immediately. Even if the email was genuinely transactional (an order confirmation, for example), the recipient has signalled they do not want to receive email from you. Continuing to send is both harmful to your reputation and potentially a legal issue.

Delivery confirmations

For time-sensitive messages like password resets or two-factor authentication codes, you can use the delivered event to confirm that the email reached the inbox. If no delivery confirmation arrives within a reasonable window, you can surface a message in your UI suggesting the user check their spam folder or try again.

Retries

If your endpoint does not return a successful response, Flexmail retries the webhook notification. Make your event handling idempotent — processing the same event twice should produce the same result as processing it once. Use the message ID and event type together to deduplicate.

Next steps

• See "Getting started with the transactional API" for account setup.
• Review the Webhooks section in the API documentation at email-api.flexmail.eu/documentation for the full payload specification and registration instructions.
• See "Transactional troubleshooting" if your webhooks are not arriving or your deliverability is below expectations.