Introduction

Email remains one of the most reliable communication channels for businesses. But integrating email into your application workflow has traditionally been painful—requiring complex IMAP connections, polling scripts, and fragile parsing logic.

MailWebhook changes this by converting incoming emails into clean, structured webhook payloads that your services can consume directly.

What You’ll Learn

In this guide, we’ll cover:

  1. Setting up your first mailbox connection
  2. Creating filters to route specific emails
  3. Defining your webhook endpoint
  4. Handling the webhook payload in your application

Step 1: Connect Your Mailbox

First, navigate to your MailWebhook dashboard and click Add Mailbox. You’ll need:

  • Your email server’s IMAP address
  • Your email credentials (we recommend using an app-specific password)
  • The mailbox folder you want to monitor (usually INBOX)
{
  "mailbox": "support@yourcompany.com",
  "server": "imap.gmail.com",
  "folder": "INBOX"
}

Step 2: Create Email Filters

Filters let you specify which emails trigger webhooks. You can filter by:

  • Sender: Match specific email addresses or domains
  • Subject: Use patterns to match subject lines
  • Body content: Search for keywords in the email body
// Example filter configuration
const filter = {
  from: "*@stripe.com",
  subject: "contains:payment",
  action: "trigger_webhook"
}

Step 3: Configure Your Webhook

Set up your webhook endpoint to receive the email data:

// Your webhook handler
app.post('/webhooks/email', async (req, res) => {
  const { from, subject, body, attachments } = req.body
  
  // Process the email
  await processIncomingEmail({
    sender: from,
    subject,
    content: body,
    files: attachments
  })
  
  res.status(200).json({ received: true })
})

Step 4: Handle the Payload

The webhook payload includes all email metadata in a structured format:

{
  "id": "msg_abc123",
  "timestamp": "2026-03-08T10:30:00Z",
  "from": {
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "to": ["support@yourcompany.com"],
  "subject": "Order #12345 - Question about shipping",
  "body": {
    "text": "Plain text content...",
    "html": "<p>HTML content...</p>"
  },
  "attachments": [
    {
      "filename": "receipt.pdf",
      "content_type": "application/pdf",
      "size": 45678,
      "url": "https://..."
    }
  ]
}

Best Practices

  1. Always verify webhook signatures to ensure requests come from MailWebhook
  2. Respond quickly with a 200 status—process heavy tasks asynchronously
  3. Implement idempotency to handle potential duplicate deliveries
  4. Use filters wisely to avoid processing unnecessary emails

Conclusion

With MailWebhook, you can build powerful email-driven workflows without managing complex infrastructure. Whether you’re building a support ticket system, processing order confirmations, or monitoring alerts, webhooks provide a reliable and scalable solution.

Ready to get started? Create your free account and start receiving email webhooks in minutes.