A direct mail API that respects your time.
RESTful endpoints, predictable JSON responses, bearer token auth, and a full sandbox, MailStream’s API is built by developers, for developers. Send your first postcard in under five minutes.
Quick start
Send a postcard in one API call.
Authenticate with your API key, pass the recipient address, and provide your creative. MailStream prints and ships within 24 hours.
- Consistent REST endpoints
- make sending, tracking, and managing mail predictable, with clean JSON responses and straightforward request patterns.
- Idempotent requests
- prevent duplicate sends and ensure safe retries, even in unreliable network conditions or high-volume workflows.
- Real-time event webhooks
- notify your systems instantly when mail is created, printed, in transit, or delivered, no polling required.
Endpoints
Everything you need. Nothing you don’t.
The MailStream API covers the full lifecycle, create, send, track, and analyze. All endpoints follow consistent patterns with predictable error handling.
Developer experience
Built for developers who ship fast.
- Bearer token auth
- Simple API key authentication via the Authorization header. No OAuth flows, no session management. Generate and rotate keys from the dashboard.
- Versioned API (v1)
- All endpoints are versioned. We won't break your integration with surprise changes. When v2 ships, v1 stays supported with a clear migration timeline.
- Sandbox mode
- Use test API keys to develop and iterate without printing or incurring charges. Sandbox responses mirror production exactly, including webhook events.
- Idempotency keys
- Pass an idempotency key with any POST request to prevent duplicate sends. Safe retries, even in unreliable network conditions.
- Pagination & filtering
- List endpoints support cursor-based pagination and filtering by status, date range, and custom metadata. Fetch exactly what you need.
- Webhooks
- Subscribe to real-time events, mail.created, mail.printed, mail.in_transit, mail.delivered. No polling required.
SDKs & libraries
Your language. Your framework.
Official SDKs for the most popular languages, plus a straightforward REST API that works with any HTTP client.
