Getting started

Sandbox

Sandbox is the free environment to develop against. You get a real API key, real iMessages going out over the wire, real webhooks firing — but every recipient must be proven yours. No risk of spamming strangers while you build.

How it works

Sign up — Clerk handles email/password. Free, no credit card.
Get an activation code — we generate a unique code like SBX-A4F2K9 tied to your account.
Text the code from your phone to the shared sandbox line we show you. Our inbound webhook matches the code → your account flips to sandbox status and your phone is bound.
Receive your API key — auto-issued, with the sk_sandbox_ prefix. Visible in Dashboard → Sandbox → API key.
Send messages — every outbound is constrained to your activated phone or one of your verified contacts. Anything else returns a friendly 400.

Why a code, not just any inbound?

Many sandbox systems (LoopMessage, SendBlue) verify a recipient by any inbound text. We require a specific per-user code so we have proof you own the phone — not just that someone texted us. Same UX, tighter guarantee.

What you can do in sandbox

Send + receive iMessages between you and the sandbox line
Fire and verify webhooks (signed with HMAC-SHA256)
Edit + unsend messages (within Apple's windows)
Test all iMessage effects (slam, balloons, confetti, invisible ink, etc.)
Send and receive reactions, typing indicators, read receipts
Test attachments + voice notes
Run an end-to-end OTP flow against your own phone

Production gives you a dedicated line, no recipient verification, and tier-based volume. Apply for production when you're ready.

The sandbox boundary

Sandbox sends are allowed only to the union of:

Your activated phone — the phone number you texted the SBX code from
Up to 5 verified contacts — phone numbers you've added that have texted a unique VRF-XXXXXX code back

If you POST to /v1/messages with a to outside that allowlist:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Sandbox accounts can only message your activated phone (+15551234567) or one of your 2/5 verified contacts. Add a contact at /dashboard/sandbox/contacts, or apply for production access.",
    "details": { "reason": "sandbox_recipient_not_allowed", "sandboxPhone": "+15551234567", "allowedCount": 3 }
  }
}

Adding verified contacts

Useful if you want to test multi-recipient flows or coordinate with a colleague. Each contact you add gets a unique VRF-XXXXXX code; they text it to the sandbox line and become a permitted recipient.

# Add a verified contact
curl -X POST 'https://api.bluereplies.com/portal/sandbox/verified-contacts' \
  -H "Authorization: Bearer $CLERK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "phoneNumber": "+15551234567" }'

# Response includes a VRF-XXXXXX code for your contact to text to the sandbox line.

Limit is 5 verified contacts per sandbox account. If you need more for an actual integration, that's the signal to apply for production.

Sandbox account lifecycle

pending-activation — signed up, hasn't texted the SBX code yet. API rejects all writes.
sandbox — activated. API key works, sends limited to allowlist.
approved — promoted to production. Dedicated line assigned, no recipient restrictions.

No expiry

Sandbox accounts don't expire. Stay in sandbox forever if you just need it for tests. API keys stay valid through promotion to production.

Applying for production

From the sandbox dashboard, click Apply for production. Tell us your business name, expected volume, and use case. We review every signup manually (usually within one business day) to keep the network healthy and your line warm.

Once approved, your sk_sandbox_ key keeps working, but you also get an sk_live_ key and a dedicated phone number with full production capacity.