Webhook Setup

Webhooks allow Mailtani to receive real-time notifications from your email provider about delivery events, bounces, complaints, and opens. This data is essential for maintaining healthy sending reputation and accurate campaign analytics.

What Webhooks Track

When Mailtani receives these events, it automatically:

• Marks contacts as Bounced on permanent bounces
• Marks contacts as Complained on spam complaints
• Stops active campaign enrollments for bounced/complained contacts
• Records delivery and open timestamps for analytics

Resend (Automatic Setup)

Webhooks are automatically registered when you verify your domain with Resend. No manual configuration is needed.

How It Works

1. When you click "Verify with Resend" on a domain, Mailtani creates a webhook endpoint via the Resend API
2. The webhook is configured to receive: email.delivered, email.bounced, email.complained, and email.opened events
3. Resend provides a signing secret that Mailtani uses to verify incoming webhook payloads

Requirements

• Your Resend API key must have Full access permission (not just "Sending access")
• If you're using a domain-scoped API key, make sure it covers the domain you're verifying

AWS SES (Automatic Setup)

Webhooks are automatically registered when you verify your domain with SES. Mailtani creates an SNS topic and SES Configuration Set for you.

How It Works

1. When you click "Verify with AWS SES" on a domain, Mailtani:
   • Creates an SNS Topic for receiving notifications
   • Subscribes your app's webhook URL to the topic
   • Creates a Configuration Set in SES
   • Adds an event destination that routes bounce, complaint, delivery, and open events to the SNS topic
2. The Configuration Set is automatically used when sending emails through that domain

Required IAM Permissions

Your IAM user needs additional permissions beyond AmazonSESFullAccess. Add the following to your IAM policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ses:*",
                "sns:CreateTopic",
                "sns:Subscribe",
                "sns:Unsubscribe",
                "sns:DeleteTopic"
            ],
            "Resource": "*"
        }
    ]
}

Alternatively, you can attach both AmazonSESFullAccess and AmazonSNSFullAccess policies to the IAM user.

SNS Subscription Confirmation

When the SNS topic subscribes to your webhook URL, AWS sends a SubscriptionConfirmation request. Mailtani handles this automatically -- no manual confirmation is needed.

Mailtrap (Manual Setup)

Mailtrap does not provide an API for webhook management, so webhooks must be configured manually in the Mailtrap dashboard.

Step-by-Step Setup

1. Log in to mailtrap.io
2. Click your avatar → Settings → Webhooks
3. Click Add new webhook
4. Fill in the form:
   • Webhook URL: https://yourapp.com/webhooks/mailtrap
   • Payload format: JSON
   • Select area: Email Sending
   • Select stream: choose your sending stream (or leave as all)
   • Select domain: choose your verified sending domain (or All domains)
5. Under Select events to listen to, enable:
   • ✅ Delivery
   • ✅ Soft Bounce
   • ✅ Bounce
   • ✅ Spam Complaint
   • ✅ Open
   • ✅ Reject
6. Click Save
7. After saving, copy the Signing Secret shown by Mailtrap
8. In Mailtani, open your domain settings and paste the signing secret into the Webhook Signing Secret field

Important Notes

• Make sure you're configuring webhooks under Email Sending, not the Inbox/Testing area
• The signing secret is used to verify that incoming webhooks are genuinely from Mailtrap
• Without the signing secret, webhook signature verification is skipped (not recommended for production)

Webhook Events by Provider

Troubleshooting

Webhooks not receiving events

• DNS not propagated: Domain verification must complete before webhooks can work. Allow up to 48 hours for DNS propagation.
• Wrong API key permissions: Resend requires "Full access" API keys. SES requires SNS permissions in addition to SES permissions.
• Firewall blocking: Ensure your server accepts POST requests on the webhook URLs from external sources.

AWS SES: Configuration Set not created

• Verify your IAM user has sns:CreateTopic and ses:CreateConfigurationSet permissions
• Check that SES is enabled in the region you selected

Mailtrap: Webhooks not verified

• Make sure you're using a Sending API token, not an Inbox testing token
• Ensure the webhook URL is publicly accessible (not behind authentication)
• The signing secret must be pasted into Mailtani for signature verification to work

Signature verification failing

• Resend: Check that your API key has full access. The signing secret is set automatically during domain verification.
• SES: SNS signature verification uses certificate-based signing. Ensure your server can reach *.amazonaws.com over HTTPS.
• Mailtrap: Verify you've entered the correct signing secret from the Mailtrap dashboard.