Skip to content

StartAuthentication

Authentication

Every API request needs a Bearer token in the Authorization header.

Last updated

API keys

Create API keys from Developer > API keys in your dashboard. Keys use sm_live_... for real traffic and sm_test_... for the sandbox. You see a key once, when you create it, so save it somewhere safe right away.

Pick scopes when you create or edit a key. You can also limit a key to some domains and mailboxes, and a key with newsletter scopes to some audiences. A limited key can't reach organization-wide endpoints such as webhooks, but it can still read and manage suppressions. Revoke a key from the dashboard whenever you like. It stops working at once and moves to a separate archived list.

An organization can hold 50 active keys. Revoked keys do not count toward that number.

IP allowlist

You can limit a key to the addresses your servers call from. In the key's form, enter up to 20 IPv4 or IPv6 addresses or CIDR ranges in Allowed IP addresses, one per line, such as 203.0.113.7 or 2001:db8::/32. An IPv4 entry also matches the same client seen as an IPv4-mapped IPv6 address. Leave the field empty to accept requests from anywhere.

A request from any other address gets a 403 authorization_error. It does not count as a failed authentication. The list applies to every request made with the key, including the hosted MCP server. OAuth access tokens are not limited by it.

Hold email to outside addresses for review

Give an AI agent's key this setting to let it write to your own team at once while a person checks everything it sends to anyone else. Turn on Hold email to outside addresses for review in the key's restrictions. The form offers it to keys that can send.

Email to your own domains sends at once. A recipient is yours when the part after the @ is exactly one of your organization's verified domains, or a verified domain whose DNS later stopped checking out. Subdomains and domains that are not verified yet do not count. When any To, Cc or Bcc recipient is someone else, POST /v1/messages, POST /v1/messages/batch and the two reply endpoints send nothing. They save the email to the mailbox's Drafts and answer 202 with a held_message. A person opens the draft in Shipmail and sends it. A held email does not count against your sending limits, and a retry with the same Idempotency-Key returns the same draft.

The draft keeps what the send asked for: the display name in from, reply_to, the reply headers, attachments, and the mailbox signature when add_signature is true. A held reply is a reply draft of its conversation, with a drf_ id, so the person's send joins that conversation. Once a new message arrives in the conversation, the review link refuses to send the reply: the person reads the new message, then opens the draft from Drafts.

client_reference, metadata and track_reply: true are kept with the draft. When a person sends it, from the inbox, the review link or the mobile app and even after editing it, the sent message gets the client_reference, metadata and batch_id, and track_reply puts the conversation in Waiting. A repeated client_reference answers with the first hold and saves no second draft, even after the draft was discarded. Once a person sent it from Shipmail, the reference answers 201 with the sent message. While the first hold is still being saved, it answers 409. The same reference held in another mailbox is a 409. A send to your own domains that names a reference still held answers 202 with that hold instead of sending.

{
  "object": "held_message",
  "status": "held_for_review",
  "draft_id": "Mabc123",
  "mailbox_id": "0b6f8d2e-3c41-4a8e-9f1d-6a2b5c7e9d10",
  "external_recipients": ["client@example.com"],
  "client_reference": "lead-42",
  "batch_id": null
}

Anything else that would reach an outside address with this key is refused with 403 authorization_error and code: "external_send_requires_review": a send that asks for scheduled_at or custom headers, a transactional sender, sending a reply draft, the inbox reply endpoints, editing a scheduled email, forwarding, newsletter test sends, calendar invitations and replies that go out, turning on an auto-reply, resuming a mailbox whose auto-reply is on or that forwards to an outside address, giving an automation a Send-mode definition that writes replies or activating or running one, and creating SMTP credentials, app passwords or a mailbox password. Pausing, disabling or renaming such an automation is allowed, and so is a calendar event saved with send_invitations: false. Newsletters to an audience are not affected.

Making requests

Pass your API key as a Bearer token:

curl https://shipmail.to/api/v1/domains \
  -H "Authorization: Bearer sm_live_..."

OAuth access tokens

Agents and command-line tools can call the API without an API key. They sign in with OAuth and send the access token as the Bearer token. The token works only on /api/v1. A token issued for the hosted MCP server is refused here, and a REST token is refused by the MCP server.

Resourcehttps://shipmail.to/api/v1
Metadatahttps://shipmail.to/.well-known/oauth-protected-resource/api/v1
FlowDynamic client registration, then authorization code with PKCE (S256)
Scopes to requestopenid profile email offline_access, plus any API scopes from the scope reference below to limit the token

Send resource=https://shipmail.to/api/v1 on both the authorize and token requests. A native client registers http://127.0.0.1/callback and may use any port when it authorizes. On the consent page you choose the organizations and permissions the client gets, and Shipmail checks them again on every request. To cut it off, revoke the connection in Developer, Connections and its tokens stop working.

OAuth scopes use the API key scope names. A client that requests API scopes, such as messages:read, gets a token that can use only those, and only within what you approved. The consent page then lists the requested scopes and offers only the permissions that hold one. A token that names no API scope can do everything you approved. A request outside the token's scopes gets 403 authorization_error with WWW-Authenticate: Bearer error="insufficient_scope" and the scope it needs. A refresh or a new authorization that drops the API scopes you approved gets invalid_scope.

When you approved more than one organization, name the one each request acts on with the X-Shipmail-Organization header. A request without it gets 400 validation_error, and an organization you did not approve gets 403 authorization_error. With one organization the header is optional.

curl https://shipmail.to/api/v1/domains \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Shipmail-Organization: <organization_id>"

An agent that cannot open a browser, such as one in a terminal or a remote shell, can get the same kind of token through agent registration: you approve it with a 6-digit code on shipmail.to.

Scopes

A key's scopes decide which endpoints it can call. Listing domains, for example, needs domains:read. A key with the * wildcard can call every endpoint.

When you create a key in Developer > API keys, presets tick common sets of scopes for you, and you can combine them. The Support preset is for a support team or a support agent. It can read mailboxes, messages and threads, list suppressed addresses and remove an address from the suppression list. It cannot send email or write drafts. The Transactional preset sends email and can read your email templates, but cannot change them.

Check which key you are using

GET /v1/capabilities works with any valid key and needs no scope. It returns the key's scopes and its resource constraints: the mailbox, domain and audience IDs it is limited to, each null when it is not limited, and hold_external_sends. Call it first when a request answers 403, to see whether the key lacks a scope or cannot reach that resource. It also returns the organization's default_timezone and whether AI models and automatic sending are in effect. aliases says how many mailbox aliases the organization has against its plan's limit, null when unlimited; adding or removing one needs mailboxes:write. The tool list below is shortened.

{
  "capability_version": "1.1.0",
  "scopes": ["calendar:read", "booking_pages:read"],
  "constraints": {
    "mailbox_ids": ["mbx_abc123"],
    "domain_ids": null,
    "audience_ids": null,
    "resource_semantics": "union-v2",
    "hold_external_sends": false
  },
  "allowed_mcp_tools": ["shipmail_get_booking_page", "shipmail_get_booking_page_slots"],
  "aliases": { "used": 3, "limit": 10 },
  "organization": {
    "default_timezone": "Europe/Paris",
    "ai": { "models_enabled": true, "automatic_send_enabled": false }
  }
}

Error response

A missing or invalid token gets a 401. The response's WWW-Authenticate header points OAuth clients to the resource metadata above:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid or missing API key.",
    "request_id": "req_abc123"
  }
}

A valid key used from an address outside its IP allowlist gets a 403:

{
  "error": {
    "type": "authorization_error",
    "message": "This API key does not accept requests from this IP address.",
    "request_id": "req_abc123"
  }
}

Scope reference

A key can hold any combination of the scopes below.

ScopePermits
domains:readList domains, get domain, verify domain
domains:writeCreate, update, delete domains
mailboxes:readList mailboxes, get mailbox
mailboxes:writeCreate, update, suspend, resume, delete mailboxes. Setting the first password at creation also needs mailbox_credentials:write
mailbox_credentials:writeSet primary mailbox passwords, create and revoke app passwords
mailboxes:exportCreate, inspect, and download mailbox content exports
members:readList and retrieve organization members
members:writeInvite people, cancel invitations, and share or unshare mailboxes with members. No preset includes it; an All access key does.
organization:readRead the default time zone and AI settings
organization:writeChange the default time zone and whether AI models are on. Acts for an Owner or Admin only.
messages:readList and retrieve messages, inbox attention queues, and reply scans
messages:writeUpdate, move, delete, and inject sandbox messages; update attention state
messages:reviewInspect and release exact message snapshots held by API-agent security review; also requires messages:read
drafts:writeCreate recipient-safe, versioned inbox reply drafts
drafts:composeSave new-message drafts to a mailbox's Drafts folder for review. Cannot send
drafts:sendSend reply drafts that already exist. Cannot write new email
messages:sendSend messages, replies, and approved reply drafts
customers:readList and retrieve customers, reply times, and customer fields
customers:writeCreate, update, sync, and delete customers
templates:readList, retrieve, and render email templates and their versions. Not needed to send a template
templates:writeCreate, update, publish, restore, and delete email templates
threads:readList threads, get thread messages
newsletters:readList and retrieve newsletter drafts and campaigns
newsletters:writeCreate, update, test, schedule, cancel, and resume newsletters
audiences:readList and retrieve newsletter audiences and their subscribers
audiences:writeCreate audiences and add, update, or remove their subscribers
automations:readList and retrieve assistant automations owned by the key creator
automations:writeCreate, update, and manually run assistant automations
suppressions:readList suppressed recipient addresses
suppressions:writeRemove addresses from the suppression list
webhooks:readList webhooks, get webhook, list deliveries, get delivery detail
webhooks:writeCreate, update, delete webhooks, rotate secret, test and replay deliveries
calendar:readList and retrieve calendar events and open availability
calendar:writeCreate, update, and delete calendar events
booking_pages:readList and retrieve booking pages
booking_pages:writeCreate, update, and delete booking pages

The calendar and booking_pages scopes do nothing until those features are turned on for your organization. See the calendar and booking pages endpoints for details.

Frequently asked questions

What happens if my API key leaks?

If a key that still works is found in public, for example in a public repository or a Docker image, Shipmail revokes it and emails the owners and admins of your organization with where it was found. Requests with that key then fail with a 401 error. Create a new key and store it as a secret. Reports come from GitHub secret scanning and Truffle Security.

Who is told when someone creates an API key?

Every owner of the organization gets an email with the key's name, its first characters and its permissions, and a link to the API keys page. An owner who creates a key is not emailed about their own key. If you did not expect the key, revoke it there.

Where should I store my API key?

In a server-side environment variable, such as SHIPMAIL_API_KEY, read at runtime. Keep it out of source control, browser bundles, client-side code and mobile apps. If it leaks, rotate it from the dashboard.

I lost my API key. Can I see it again?

No. You see the full key once, when you create it. Revoke the lost key in the dashboard, create a new one, and update every service that used the old one.

What is a scope and how do I pick the right one?

A scope limits what a key can do. Give each key only the scopes it needs. A service that only sends email gets messages:send, not the wildcard. If that key leaks, it can send email and nothing else.

Can I use the same API key for production and staging?

Use a live key in production and a test key in staging. Test keys work on separate sandbox data and never deliver real email. Give each service its own key so you can scope and revoke them one at a time.