Webhooks

Overview

Webhooks let your application receive real-time HTTP notifications when email events occur — deliveries, opens, clicks, bounces, and unsubscribes. Instead of polling the API, SentinMail pushes events to your server as they happen.

Set Up a Webhook

1. Create an Endpoint on Your Server

Your webhook receiver should:

Accept POST requests
Return a 200 status to acknowledge receipt
Process the payload asynchronously (respond fast, process later)

Example (Node.js / Express):

Code

javascript

1app.post('/webhooks/sentinmail', (req, res) => {
2  const event = req.body;
3  console.log(`Received event: ${event.type} for ${event.recipient}`);
4 
5  // Acknowledge immediately
6  res.status(200).send('OK');
7 
8  // Process async
9  processEmailEvent(event);
10});

Example (Python / Django):

Code

python

1from django.http import HttpResponse
2from django.views.decorators.csrf import csrf_exempt
3import json
4 
5@csrf_exempt
6def sentinmail_webhook(request):
7    if request.method == 'POST':
8        event = json.loads(request.body)
9        print(f"Received: {event['type']} for {event['recipient']}")
10 
11        # Process async (e.g., queue to Celery)
12        process_email_event.delay(event)
13 
14        return HttpResponse(status=200)

2. Register the Webhook

Code

bash

1curl -X POST "https://api.sentinmail.app/api/emails/webhook-endpoints/" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": "https://yourapp.com/webhooks/sentinmail",
6    "events": ["delivered", "opened", "clicked", "bounced", "unsubscribed"]
7  }'

Field	Type	Required	Description
`url`	string	Yes	Your HTTPS webhook endpoint
`events`	array	Yes	Event types to subscribe to

3. Start Receiving Events

SentinMail will POST event data to your URL as events occur.

Event Types

Event	Triggered When	Priority
`delivered`	Email accepted by recipient's mail server	Low
`opened`	Recipient opened the email	Low
`clicked`	Recipient clicked a tracked link	Low
`bounced`	Email delivery failed	High
`unsubscribed`	Recipient clicked unsubscribe	High

Tip

At minimum, subscribe to `bounced` and `unsubscribed` — these are critical for maintaining list hygiene and compliance. Ignoring bounces can damage your sender reputation.

Event Payload

Each webhook POST contains a JSON payload:

Code

json

1{
2  "id": "evt-uuid-here",
3  "type": "opened",
4  "recipient": "user@example.com",
5  "sent_email_id": "sent-uuid-here",
6  "campaign_id": "camp-uuid-here",
7  "metadata": {
8    "user_agent": "Mozilla/5.0...",
9    "ip": "203.0.113.42"
10  },
11  "timestamp": "2026-04-02T14:30:00Z"
12}

Manage Webhooks

List All Webhooks

Code

bash

1curl -X GET "https://api.sentinmail.app/api/emails/webhook-endpoints/" \
2  -H "X-API-Key: YOUR_API_KEY"

Update a Webhook

Code

bash

1curl -X PUT "https://api.sentinmail.app/api/emails/webhook-endpoints/WEBHOOK_ID/" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": "https://yourapp.com/webhooks/sentinmail-v2",
6    "events": ["bounced", "unsubscribed"]
7  }'

Delete a Webhook

Code

bash

1curl -X DELETE "https://api.sentinmail.app/api/emails/webhook-endpoints/WEBHOOK_ID/" \
2  -H "X-API-Key: YOUR_API_KEY"

Best Practices

Respond with 200 immediately — process the event asynchronously to avoid timeouts
Handle duplicates — use the event id to deduplicate, as webhooks may be retried
Use HTTPS — webhook URLs must use HTTPS for security
Monitor bounces — high bounce rates damage your sender reputation; automatically remove invalid addresses
Log everything — store raw webhook payloads for debugging and audit trails

Documentation

Webhooks

Overview

Set Up a Webhook

1. Create an Endpoint on Your Server

2. Register the Webhook

3. Start Receiving Events

Event Types

Event Payload

Manage Webhooks

List All Webhooks

Update a Webhook

Delete a Webhook

Best Practices