Skip to content

StartAPI overview

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/v1

Conventions

  • Authenticate with a Bearer token in the Authorization header.
  • Request and response bodies use JSON with snake_case field names.
  • Every response has an X-Request-Id header. Include it when you ask us about a request.
  • Timestamps are ISO 8601 strings in UTC.
  • Every object carries an object field 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.