Email best practices
What is a webhook? Real-time email event tracking with Mailjet
Find out what exactly and why you need it. Tracking events is easy using webhooks, this is why Mailjet offers you the possibility to use them with us.
Email best practices
Webhooks are a powerful way to receive real-time notifications when events occur in your email campaigns. This comprehensive guide will teach you what webhooks are, how they work with email systems, and how to implement Mailjet’s webhook functionality to track email events like opens, clicks, bounces, and more in real time.
By the end of this guide, you’ll understand how to set up and optimize webhook endpoints, handle different event types, and implement best practices for reliable, scalable email event processing.
A webhook is a simple way for one system to notify another that “something just happened.” It’s an HTTP POST request sent to a URL you provide (your “webhook endpoint”) containing a JSON payload that describes the event. Unlike APIs that you poll on a schedule, webhooks are event-driven as they push data only when there’s something new to report.
Think of webhooks as the internet’s version of a phone call: instead of repeatedly checking if something happened, the system calls you immediately when it does.
Webhooks offer several advantages for email marketing and transactional email workflows:
Understanding the difference between webhooks and traditional email API polling helps illustrate why webhooks are often the better choice:
| API polling | Webhooks |
|---|---|
| Pull data on a timer, even if nothing changed | Event-based push notifications |
| More requests and bandwidth usage | Fewer requests, more efficient |
| Delayed insights due to polling intervals | Instant updates when events occur |
| Complex scheduling and state management | Simpler automation workflows |
Mailjet can send webhook notifications for the following email events:
Each webhook contains a JSON payload with event-specific information. Here are examples of common event types:
{
"event": "open",
"time": 1433103519,
"MessageID": 19421777396190490,
"email": "api@mailjet.com",
"mj_campaign_id": 7173,
"mj_contact_id": 320,
"customcampaign": "",
"CustomID": "helloworld",
"Payload": "",
"ip": "127.0.0.1",
"geo": "US",
"agent": "Mozilla/5.0 ..."
}
{
"event": "bounce",
"time": 1430812195,
"MessageID": 13792286917004336,
"email": "bounce@mailjet.com",
"blocked": true,
"hard_bounce": true,
"error_related_to": "recipient",
"error": "user unknown"
}
Each event type requires different handling strategies:
Following these best practices ensures reliable webhook processing and optimal performance:
Mailjet automatically retries failed webhook deliveries for up to 24 hours if your endpoint doesn’t return a 200 OK response. If repeated errors persist, the webhook URL may be suspended. You can configure a backup URL to ensure continuous event delivery.
You can configure Mailjet webhooks using either the API or the web interface. Here are both approaches:
This method offers more control and is ideal for automated deployments.
Decide which events you want to track: sent, open, click, bounce, blocked, spam, or unsub.
Use the eventcallbackurl resource to configure your webhook:
curl -X POST \
https://api.mailjet.com/v3/REST/eventcallbackurl \
-H 'Authorization: Basic <base64_encoded_api_key:secret>' \
-H 'Content-Type: application/json' \
-d '{
"EventType": "open",
"Url": "https://example.com/webhooks/mailjet/open",
"Version": 2
}'
Configuration notes:
Send a test email and perform the tracked action (open, click, etc.) to verify you receive webhook events.
For teams preferring a visual interface:
Here are minimal webhook receiver implementations in popular programming languages:
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhooks/mailjet/open', (req, res) => {
// 1. Persist the event data quickly
console.log('Received webhook:', req.body);
// TODO: Save to queue or database
// await saveToQueue(req.body);
// 2. Acknowledge immediately
res.status(200).send('ok');
});
app.listen(3000, () => {
console.log('Webhook server running on port 3000');
});
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhooks/mailjet/open', methods=['POST'])
def handle_open_event():
data = request.get_json()
# Process the webhook data
print(f"Received webhook: {data}")
# TODO: Save to queue or database
# save_to_queue(data)
return jsonify({"status": "ok"}), 200
if __name__ == '__main__':
app.run(port=3000)
Here are some tips to help you get even more from webhooks.
Use Version=2 in your webhook configuration to reduce HTTP overhead by receiving multiple events in batched requests:
{
"EventType": "open",
"Url": "https://example.com/webhooks/mailjet/batch",
"Version": 2
}
Use CustomID and EventPayload parameters in your Send API calls to make webhook events easier to correlate with your internal systems:
{
"Messages": [{
"To": [{"Email": "user@example.com"}],
"Subject": "Welcome!",
"TextPart": "Welcome to our service!",
"CustomID": "user-123-welcome",
"EventPayload": "campaign=onboarding&segment=new_users"
}]
}
For high-volume applications, consider streaming events to third-party queue services:
Mailjet sends sent, open, click, bounce, blocked, spam, and unsub events. Each contains the MessageID, contact and campaign identifiers, and event-specific details (such as url for click events).
Events are pushed shortly after they occur, typically within seconds. If your endpoint doesn’t respond with HTTP 200 OK, Mailjet retries delivery for up to 24 hours.
Yes. Configure grouped delivery by setting Version=2 on your eventcallbackurl so Mailjet batches multiple events in one POST request.
Use HTTPS, protect the endpoint with basic authentication, and restrict access through IP filtering or API gateways. Always process payloads server-side and never expose webhook endpoints to client applications.
Follow this checklist to implement Mailjet webhooks successfully:
Now that you understand webhook fundamentals and implementation, consider exploring these related Mailjet features:
Webhooks provide a powerful, efficient way to receive real-time notifications about email events. By implementing Mailjet webhooks with proper error handling, security measures, and asynchronous processing, you can build responsive, data-driven email workflows that enhance customer experience and improve operational efficiency.
Remember to start simple, monitor your implementation closely, and scale your webhook processing as your email volume grows. With the foundation provided in this guide, you’re ready to harness the full power of real-time email event tracking.
