Bounce Webhook

Docs index for AI agents: https://mailvalid.io/llms.txt. Every docs page is also available as Markdown: add .md to its URL.

Send your delivery and bounce data back to MailValid to make future verifications more accurate. This matters most for providers that block SMTP verification, such as Microsoft and Apple, where MailValid can't confirm mailboxes directly.

The more bounce data you send, the more accurate future verifications get. MailValid checks this history before running SMTP verification, so known addresses return results instantly.

POST https://mailvalid.io/api/v1/webhooks/bounce

API key required. Submitting events is free.

Submit bounce and delivery events

Send up to 1,000 bounce or delivery events per request. Hard bounces automatically invalidate cached verification results.

Event types

Request body

{
  "events": [
    {
      "email": "user@example.com",
      "event_type": "hard_bounce",
      "bounce_code": "550",
      "bounce_message": "User unknown",
      "timestamp": "2026-03-14T10:30:00Z"
    },
    {
      "email": "valid@example.com",
      "event_type": "delivered"
    }
  ]
}

Example

curl -X POST https://mailvalid.io/api/v1/webhooks/bounce \
  -H "X-API-Key: mv_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"email": "bounced@example.com", "event_type": "hard_bounce", "bounce_code": "550"},
      {"email": "good@example.com", "event_type": "delivered"}
    ]
  }'

Response

{
  "success": true,
  "processed": 2,
  "errors": 0,
  "message": "Processed 2/2 events"
}