Bounce House

Your email sending provider's dashboard shows you what happened to messages sent through that provider. But if you send through more than one (production on SendGrid, transactional on Postmark, marketing on Mailgun), you're checking three dashboards to understand your deliverability. None of them can tell you how your overall sender reputation is trending, whether bounces on one provider correlate with DNS issues visible in your DMARC reports, or whether an address that hard-bounced on SendGrid is still being sent to through Postmark.

Bounce House connects all of your providers into a single normalized event stream. Delivery, bounce, complaint, open, click, and unsubscribe events all arrive in one common format regardless of which provider sent them. Bounced and complained addresses are automatically added to a unified suppression list, so a hard bounce on SendGrid is visible before you send to that address through Postmark. And because provider events are correlated with your domain health data, a spike in bounces can trigger a DNS audit and surface the root cause.

Supported providers

SendGrid — HMAC-SHA256 signature verification
Postmark — webhook signature verification
Mailgun — webhook signature verification
AWS SES — SNS signature verification with automatic subscription confirmation

Connect a provider

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/providers \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"provider": "sendgrid", "signing_secret": "<your-verification-key>"}'

Returns {id, provider, enabled, config, created_at}. Signing secrets are encrypted at rest.

Then point your provider's webhook URL to:

https://api.bouncehouse.cloud/webhooks/provider/{account_id}/sendgrid

Inbound webhooks are verified against the provider's signing secret (not your API key) and rate-limited to 300 requests/minute per account. For AWS SES, SNS subscription confirmations are handled automatically.

Normalized event types

Each provider uses its own event names and formats. Bounce House normalizes them into a common schema:

Normalized type	What happened
`delivered`	Message accepted by the recipient's mail server
`bounced`	Message rejected (classified as hard or soft, with bounce category)
`deferred`	Temporary delivery failure, provider will retry
`dropped`	Provider refused to send (suppression, rate limit, etc.)
`opened`	Recipient opened the message
`clicked`	Recipient clicked a link in the message
`complained`	Recipient marked the message as spam or unsubscribed

Bounces include bounce_type (hard or soft) and bounce_category (invalid address, mailbox full, etc.) so you can distinguish between permanent failures and transient issues.

Auto-suppression

When any connected provider reports a hard bounce or spam complaint, the recipient address is automatically added to your suppression list. Soft bounces (transient failures like a full mailbox) are excluded since they may resolve on their own. This works across all providers: a complaint reported by SendGrid suppresses the address globally, not just for SendGrid.

Fan-out

Forward normalized events to your own endpoints for triggering downstream workflows, updating CRM records, or feeding analytics pipelines:

# Add a fan-out URL
curl -X POST https://api.bouncehouse.cloud/api/accounts/me/providers/{config_id}/fanout-urls \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-app.com/webhooks/email-events"}'

# List current fan-out URLs
curl https://api.bouncehouse.cloud/api/accounts/me/providers/{config_id}/fanout-urls \
  -H "Authorization: Bearer bh_your_key"

Fan-out deliveries use exponential backoff retry (30s, 2m, 10m, 30m, 2h) with configurable max attempts. Server errors and rate limits trigger retries; client errors (4xx except 429) are treated as permanent failures. You can track delivery status and manually retry failed deliveries via the deliveries API.

List providers

curl https://api.bouncehouse.cloud/api/accounts/me/providers \
  -H "Authorization: Bearer bh_your_key"

Remove a provider

curl -X DELETE https://api.bouncehouse.cloud/api/accounts/me/providers/{config_id} \
  -H "Authorization: Bearer bh_your_key"

Auth providers

Separately from email sending providers, you can connect authentication providers to monitor auth-related email events: signup confirmations, password resets, MFA challenges, and magic link sends.

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/auth-providers \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"provider": "auth0", "config": {...}}'

Supported: Auth0, Clerk, Supabase, Neon Auth, Firebase, Cognito.

Auth events are stored as messages with channel: "auth_event" and include the auth event type, user email, sending service (which ESP the auth provider uses), and source IP. When a verification email later arrives at a receiver, Bounce House correlates the two events and calculates the actual email delivery latency, giving you data on how long your auth provider's ESP takes to deliver.

curl https://api.bouncehouse.cloud/api/accounts/me/auth-providers/{config_id}/events \
  -H "Authorization: Bearer bh_your_key"

Providers