# Bounce Webhook

> Docs index for AI agents: [https://mailvalid.io/llms.txt](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

| Event type | Effect | Description |
|---|---|---|
| `delivered` | Marks valid | Email was successfully delivered to inbox |
| `hard_bounce` | Marks invalid | Permanent bounce — mailbox doesn't exist (550) |
| `soft_bounce` | Recorded | Temporary bounce — mailbox full, server down (452) |
| `complaint` | Marks do_not_mail | Recipient marked email as spam |
| `unsubscribe` | Recorded | Recipient unsubscribed from emails |

## Request body

```json
{
  "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

```bash
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

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