Black Friday Sale

Use code: BLACKFRIDAY50

50% OFF on all prices
Ends in: 00d: 00h: 00m: 00s

MailValid Webhooks: Results the Moment a Bulk Job Ends

Get the results posted to your app the moment a bulk job finishes. No polling.

Signed with HMAC-SHA256 · Retried up to 5 times · Bounce events free to submit

How it works

Set up in three steps

  1. 1

    Add webhook_url to a bulk job

    Tell MailValid where to post the results when the job ends.

    POST /api/v1/verify/bulk
    
    {
      "emails": ["…"],
      "webhook_url": "https://your-app.com/hook"
    }
  2. 2

    Check the signature

    Compare an HMAC-SHA256 of the raw body with the signature header.

    expected = hmac.new(secret, raw_body,
                        hashlib.sha256).hexdigest()
    hmac.compare_digest(expected, signature)
  3. 3

    Act on the event

    Use the counts, then fetch the full results from results_url.

    job.completed

    total_emails100
    valid_count85
    invalid_count15
    Fetch results_url
Events

What each delivery tells you

The X-MailValid-Event header says what happened. Every delivery is signed with X-Mailvalid-Signature.

  • job.completedFinished. Counts, credits used and a results_url.
  • job.failedFailed. error_message says why.
  • job.cancelledCancelled. Reserved credits were released.
Bounce feedback

Send bounces back, get sharper results

POST delivery and bounce events to /api/v1/webhooks/bounce, up to 1,000 per request. It's free.

  • delivered Marks the address valid.
  • hard_bounce Marks it invalid and clears cached results.
  • soft_bounce Recorded. Mailbox full or server down.
  • complaint Marks it do_not_mail.
  • unsubscribe Recorded.

Bounce webhook docs

Good to know

Three quick tips

  • Check the signature on the raw body, before parsing the JSON.

  • Your webhook secret is in the dashboard.

  • Failed deliveries are retried up to 5 times, with growing gaps.

FAQ

Questions about MailValid for Webhooks

When does MailValid send a webhook?

When a bulk job you submitted with a webhook_url ends. The X-MailValid-Event header says how: job.completed, job.failed or job.cancelled.

How do I know a webhook really came from MailValid?

Every delivery has an X-Mailvalid-Signature header: an HMAC-SHA256 of the raw request body, signed with your account's webhook secret. Recompute it over the exact bytes you receive and compare.

Where do I find my webhook secret?

In your dashboard. It's also returned as webhook_secret from GET /api/auth/stats.

What if my endpoint is down?

Failed deliveries are retried with exponential backoff (1, 2, 4, 8 and 16 minutes), up to 5 attempts.

Does sending bounce events cost credits?

No. Submitting bounce and delivery events to the bounce webhook is free.

Stop polling. Get a webhook instead.

Create a free account, submit a bulk job with a webhook_url and get the results as soon as they're ready.

Get your free API key