Messages

Bounce House receives content from many different sources: forwarded operational email, webhook payloads captured by ephemeral receivers, delivery and bounce events from your sending providers, SMS messages, and auth provider notifications. Without a unified view, you'd need to check each source separately to understand what's happening across your email infrastructure.

Messages are the unified view. Every piece of inbound content, regardless of how it arrived, is stored as a message that you can query through a single API. Filter by channel, tag, sender, or time range, and paginate through results with cursors.

Automatic content extraction

Every email and webhook message is processed through an extraction pipeline that surfaces structured data from unstructured content. The pipeline runs five extractors:

• OTP codes — 4-8 digit codes near keywords like "code," "verify," or "confirm"
• Verification links — URLs with paths like /verify, /confirm, /activate, or query parameters like ?token=
• Auth provider links — Links from Auth0, Clerk, Supabase, Firebase, Cognito, Neon Auth, WorkOS, and Stytch, classified by provider and purpose (verification, password reset, magic link, invitation)
• OAuth parameters — Authorization codes, state parameters, and access tokens from query parameters, JSON bodies, and URLs
• Unsubscribe links — RFC 2369 List-Unsubscribe headers, RFC 8058 one-click unsubscribe, and unsubscribe URLs in the body

Results are merged into the extracted field:

{
  "otp_codes": ["123456"],
  "verification_links": ["https://example.com/verify?token=abc"],
  "provider_links": [{ "provider": "auth0", "purpose": "verification", "url": "https://..." }],
  "oauth": { "code": "auth_code", "state": "csrf_token" },
  "unsubscribe": {
    "header_urls": ["https://example.com/unsub"],
    "one_click": true,
    "body_urls": ["https://example.com/opt-out?id=123"]
  }
}

Extractor failures are isolated: if one fails, the error is logged in extracted._errors and the others still run.

Channels

Messages arrive through five channels, each with channel-specific metadata:

Email messages preserve the full raw RFC 5322 payload for replay or forensic analysis. Attachment metadata (filename, content type, size) is stored, though full attachment data is not retained.

Query messages

curl "https://api.bouncehouse.cloud/api/accounts/me/messages?channel=email&tag=abuse&limit=50" \
  -H "Authorization: Bearer bh_your_key"

Returns {items: [...], pagination: {next_cursor, has_more}}.

Query parameters:

• channel — email, webhook, provider_event, sms, auth_event
• tag — filter by routing tag (exact match)
• sender — filter by sender (substring match)
• since — ISO timestamp
• cursor — pagination cursor (from next_cursor)
• limit — results per page (max 200, default 50)

Pagination is cursor-based using created_at timestamps. Pass the next_cursor value to get the next page.

Get a message

curl https://api.bouncehouse.cloud/api/accounts/me/messages/{message_id} \
  -H "Authorization: Bearer bh_your_key"

Returns the full message detail including body text, HTML, headers, attachments, extracted content, and channel-specific metadata.

Delete a message

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

Retention

Configure per-channel retention periods:

curl -X PATCH https://api.bouncehouse.cloud/api/accounts/me/retention \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email_days": 30,
    "webhook_days": 7,
    "provider_event_days": 90,
    "sms_days": 7,
    "auth_event_days": 30
  }'

Messages older than the configured retention period are automatically purged. Messages linked to ephemeral receivers inherit the receiver's expiry time. Linked resources (events, webhook deliveries) are cleaned up in the same purge cycle.