📧Email Events

Webhook events for Email service.

Overview

Currently, the Email service does not support webhooks in Docs-Dispatcher v1.0.

Email dispatch uses SMTP directly, which provides immediate send/fail responses but does not offer webhook-based event tracking for delivery status, opens, or clicks.

Why No Webhooks?

Email dispatch via SMTP is synchronous and completes immediately:

Immediate Send: Email is handed to SMTP server in <1 second
Quick Response: Success/failure returned immediately
No Delivery Tracking: SMTP doesn't provide delivery/open/click events

Typical workflow:

// Email dispatch is synchronous
const response = await fetch('/api/email', {
  method: 'POST',
  body: JSON.stringify({
    from: '[email protected]',
    to: ['[email protected]'],
    subject: 'Hello',
    template: { id: 123, data: {} }
  })
});

const { success, messageId } = await response.json();
console.log('Email sent:', messageId); // Immediate result

What About Delivery/Opens/Clicks?

SMTP Limitations:

✅ Immediate send confirmation
❌ No delivery notifications (recipient received email)
❌ No open tracking (recipient opened email)
❌ No click tracking (recipient clicked links)

For advanced tracking, use dedicated email service providers instead of SMTP.

Alternative: Email Service Providers

For delivery tracking, opens, and click analytics, integrate directly with email platforms:

SendGrid Webhooks

// Direct SendGrid integration (not via Dispatcher)
const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);

await sgMail.send({
  to: '[email protected]',
  from: '[email protected]',
  subject: 'Hello',
  html: '<strong>Message</strong>'
});

// Configure webhook in SendGrid dashboard
app.post('/webhooks/sendgrid', (req, res) => {
  const events = req.body;

  events.forEach(event => {
    console.log(`Event: ${event.event}`); // 'delivered', 'open', 'click'
    console.log(`Email: ${event.email}`);
  });

  res.status(200).send();
});

Brevo (formerly Sendinblue) Webhooks

// Brevo API integration
const SibApiV3Sdk = require('sib-api-v3-sdk');
const apiInstance = new SibApiV3Sdk.TransactionalEmailsApi();

await apiInstance.sendTransacEmail({
  sender: { email: '[email protected]' },
  to: [{ email: '[email protected]' }],
  subject: 'Hello',
  htmlContent: '<strong>Message</strong>'
});

// Webhook handler
app.post('/webhooks/brevo', (req, res) => {
  const { event, email } = req.body;

  if (event === 'delivered') {
    console.log('Email delivered to:', email);
  }

  res.status(200).json({ received: true });
});

Configure webhook: Brevo Dashboard → Settings → Webhooks

Mailgun Webhooks

const mailgun = require('mailgun-js')({
  apiKey: process.env.MAILGUN_API_KEY,
  domain: 'yourdomain.com'
});

await mailgun.messages().send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Hello',
  html: '<strong>Message</strong>'
});

// Webhook handler with signature verification
app.post('/webhooks/mailgun', (req, res) => {
  const { signature, event, recipient } = req.body;

  // Verify signature
  if (!mailgun.validateWebhook(signature)) {
    return res.status(401).send('Invalid signature');
  }

  console.log(`Event: ${event['event']}`); // 'delivered', 'opened', 'clicked'

  res.status(200).send();
});

Planned Future Support

Email webhook support is planned for v2.0:

Planned Events:

email.sent - Email successfully handed to SMTP server
email.delivered - Email delivered to recipient's inbox
email.bounced - Email bounced (invalid address, full inbox)
email.opened - Recipient opened the email
email.clicked - Recipient clicked a link
email.spam - Marked as spam by recipient
email.unsubscribed - Recipient unsubscribed

Coming in v2.0 (Q4 2026): Webhook support for email events via integrated ESPs. Subscribe to the changelog for updates.

Current Workarounds

1. Use Sync Mode (Default)

Email dispatch returns immediately:

curl -X POST https://api.docs-dispatcher.io/api/email \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Hello",
    "template": { "id": 123, "data": {} }
  }'

# Immediate response
{
  "success": true,
  "messageId": "<[email protected]>"
}

2. SMTP Bounce Handling

Monitor bounce emails:

// Configure SMTP bounce address
const smtpConfig = {
  from: '[email protected]',
  returnPath: '[email protected]' // Receive bounce notifications
};

// Process bounce emails
app.post('/email/bounce', (req, res) => {
  const { recipient, bounceType, message } = req.body;

  if (bounceType === 'hard') {
    // Permanent failure - remove from list
    await db.contacts.update({
      where: { email: recipient },
      data: { status: 'bounced' }
    });
  }

  res.status(200).send();
});

3. Direct ESP Integration

Use email service providers directly for advanced features:

Provider

Delivery Tracking

Opens

Clicks

Webhooks

Docs

SendGrid

✅ Yes

Link

Brevo

✅ Yes

Link

Mailgun

✅ Yes

Link

Amazon SES

✅ Yes

Link

Postmark

✅ Yes

Link

4. Email Analytics Platforms

Use analytics platforms for tracking:

Google Analytics: Add UTM parameters to links in emails:

const emailHtml = `
  <a href="https://example.com/product?utm_source=email&utm_medium=email&utm_campaign=newsletter">
    View Product
  </a>
`;

Track in Google Analytics to see email-driven traffic.

Async Mode (Without Webhooks)

You can use async mode, but no webhook is sent:

curl -X POST "https://api.docs-dispatcher.io/api/email?async=true" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d @email-request.json

# Response (no webhook sent)
{
  "success": true,
  "dispatchId": "disp_xyz789",
  "status": "queued"
}

Note: Email will be sent, but no delivery/open/click notifications.

Comparison with Webhook Services

Feature

eSign

Postal

Webhook Support

❌ No

✅ Yes

Delivery Tracking

❌ No

✅ Yes

Response Time

<1 sec

30-300 sec

60-600 sec

Best Mode

Sync

Async + Webhook

Best Practices

Track Engagement Without Webhooks

1. Tracking Pixels:

<img src="https://yourapp.com/track/email-open?id=abc123" width="1" height="1" />

2. Link Redirects:

<a href="https://yourapp.com/track/click?id=abc123&target=product">Click Here</a>

3. UTM Parameters:

<a href="https://example.com?utm_source=email&utm_medium=campaign&utm_id=abc123">Visit</a>

Handle Bounces

Configure bounce handling:

// SMTP config with bounce address
const smtpConfig = {
  from: '[email protected]',
  returnPath: '[email protected]'
};

// Monitor [email protected] inbox
const imaps = require('imap-simple');

async function processBounces() {
  const connection = await imaps.connect({
    imap: {
      host: 'imap.example.com',
      user: '[email protected]',
      password: process.env.BOUNCE_PASSWORD
    }
  });

  const messages = await connection.search(['UNSEEN']);

  for (const message of messages) {
    const bounceInfo = parseBounceEmail(message);
    await handleBounce(bounceInfo.recipient, bounceInfo.type);
  }

  connection.end();
}

setInterval(processBounces, 5 * 60 * 1000); // Every 5 minutes

Next Steps

Email Recipe - Complete email dispatch workflow
Sync vs Async - When to use each mode
eSign Webhooks - Services that do support webhooks
Webhook Fundamentals - How webhooks work
Providers Overview - All available providers

hashtagOverview

hashtagWhy No Webhooks?

hashtagWhat About Delivery/Opens/Clicks?

hashtagAlternative: Email Service Providers

hashtagSendGrid Webhooks

hashtagBrevo (formerly Sendinblue) Webhooks

hashtagMailgun Webhooks

hashtagPlanned Future Support

hashtagCurrent Workarounds

hashtag1. Use Sync Mode (Default)

hashtag2. SMTP Bounce Handling

hashtag3. Direct ESP Integration

hashtag4. Email Analytics Platforms

hashtagAsync Mode (Without Webhooks)

hashtagComparison with Webhook Services

hashtagBest Practices

hashtagTrack Engagement Without Webhooks

hashtagHandle Bounces

hashtagNext Steps

hashtagGetting Notified of Updates

Overview

Why No Webhooks?

What About Delivery/Opens/Clicks?

Alternative: Email Service Providers

SendGrid Webhooks

Brevo (formerly Sendinblue) Webhooks

Mailgun Webhooks

Planned Future Support

Current Workarounds

1. Use Sync Mode (Default)

2. SMTP Bounce Handling

3. Direct ESP Integration

4. Email Analytics Platforms

Async Mode (Without Webhooks)

Comparison with Webhook Services

Best Practices

Track Engagement Without Webhooks

Handle Bounces

Next Steps

Getting Notified of Updates