API overview
Manage domains, mailboxes, members, messages, automations, and webhooks over HTTP. Every endpoint lives under one base URL and follows the same rules.
Last updated
Base URL
https://shipmail.to/api/v1Conventions
- Authenticate with a Bearer token in the
Authorizationheader. - Request and response bodies use JSON with
snake_casefield names. - Every response has an
X-Request-Idheader. Include it when you ask us about a request. - Timestamps are ISO 8601 strings in UTC.
- Every object carries an
objectfield naming its type (e.g.domain,mailbox,message). - Most IDs are prefixed strings (e.g.
msg_,thd_,whk_). Domains and mailboxes use bare UUIDs.
Key concepts
You need these six for almost every request. Each one has its own page.
Authentication
Send a Bearer token in the Authorization header on every request. An API key belongs to your account. Its scopes decide what it can call, and you can limit it to some domains and mailboxes.
Pagination
List endpoints page with a cursor. Each response has a pagination object with has_more and next_cursor. To get the next page, pass next_cursor back as the cursor query parameter.
Idempotency
POST, PATCH, and PUT requests accept an Idempotency-Key header. Retry with the same key within 24 hours and you get the original response back, with no duplicate created.
Rate limits
Your plan sets your rate limit. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Go over it and you get 429 Too Many Requests.
Errors
Every error has the same type, message, and code fields. Status codes mean what you'd expect: 400 for bad input, 401 for missing auth, 404 for not found, 429 for rate limits.
Webhooks
When an event happens, such as message.received, Shipmail sends a POST to your URL with a signature header you can verify. A failed delivery is retried up to 5 times with exponential backoff.
Reference
Authentication
Create API keys and authenticate requests with Bearer tokens.
Errors
Error envelope format, error types, and status codes.
Rate limits
Request quotas per plan and the headers that report them.
Pagination
Cursor-based pagination for list endpoints.
Idempotency
Retry a POST without sending it twice.
Plan limits
Per-plan quotas for mailboxes, domains, and audience adds.
Domains
Create, list, update, delete, and verify domains.
Mailboxes
Create, list, update, and delete mailboxes on your domains.
Members
List and retrieve organization members.
Organization settings
Read and change the default time zone and AI switches.
Messages
Send email and retrieve individual messages.
Templates
Store email templates with variables, publish versions, and send them by ID.
Threads
List threads, view thread messages, and reply to threads.
Reply scans
Scan past inbox threads for ones nobody answered.
SMTP credentials
Let SMTP clients send as a transactional sender.
Transactional domains
Create and verify the sending subdomains of transactional email.
Transactional senders
Create, turn off and move the From addresses your app sends from.
Suppressions
List suppressed recipients and remove addresses after remediation.
Audiences
Add, list, update, unsubscribe, and resubscribe newsletter subscribers.
Segments
Save groups of an audience's subscribers and target newsletter blocks at them.
Automations
Create, version, pause, and manually run assistant automations.
Newsletter domains
List newsletter sending domains and inspect their verification status.
Newsletter sender identities
List reusable From and footer identities for newsletter drafts.
Newsletters
Create drafts, send tests, run preflight, and schedule newsletter campaigns.
Calendar
List, create, and update calendar events and query open availability.
Booking pages
Create and manage public booking pages for scheduling meetings.
Webhooks
Subscribe to events with HTTPS webhooks.
Webhook verification
Verify webhook signatures and prevent replay attacks.
Status
A health check to point your monitoring at.