Getting Started

From zero to your first received email in 5 minutes.

1Create an account and get an API key

bash

curl -X POST https://api.bouncehouse.cloud/api/accounts \
  -H "Content-Type: application/json" \
  -d '{"name": "My App"}'

# Response includes your API key (save it — you can't retrieve it later):
# {"id": "...", "api_key": "bh_..."}

Account created. API key starts with bh_ — store it securely.

2Create an email receiver

bash

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/receivers \
  -H "Authorization: Bearer bh_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"channel": "email", "label": "signup-test", "ttl_seconds": 3600}'

# Response includes the receiver address:
# {"id": "...", "address_or_url": "signup-test_rx_a3b4c5d6@acme.a001-bo.ing-bo.ing"}

Receiver created. Send an email to the address above.

3Wait for a message

Send an email to the receiver address (or trigger your app to send one), then query for it. The wait endpoint long-polls — no polling loop needed.

bash

BASE=https://api.bouncehouse.cloud/api/accounts/me
curl "$BASE/receivers/{id}/wait?timeout=30" \
  -H "Authorization: Bearer bh_..."

# {
#   "from": "noreply@example.com",
#   "subject": "Verify your email",
#   "extracted": {
#     "otps": ["483291"],
#     "links": ["https://example.com/verify?t=..."]
#   }
# }

Message received in 340ms. OTP extracted: 483291.

4Add a domain for DMARC monitoring

Add your domain to start receiving DMARC reports and health assessments. This is unmetered — no usage charges regardless of how many domains you add.

bash

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/domains \
  -H "Authorization: Bearer bh_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

# Then check your domain health:
curl https://api.bouncehouse.cloud/api/accounts/me/domains/example.com/health \
  -H "Authorization: Bearer bh_abc123..."

Domain health: 7/10. 2 recommendations available.

5Set up provider webhook fan-out

Point your sending provider’s webhook at Bounce House. We process the events and fan out to your endpoints — no more single-destination limits.

bash

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/providers \
  -H "Authorization: Bearer bh_..." \
  -H "Content-Type: application/json" \
  -d '{"provider": "sendgrid", "signing_secret": "sg_..."}'

Provider configured. Point your SendGrid webhook URL to the endpoint above.