Start with the smallest set of scopes your integration needs. The key fixes the workspace that every data request can access.
The public contract
| Element | MailSequence behavior |
|---|---|
| Base path | https://app.mailsequence.com/api/v1 |
| Authentication | Bearer API key |
| Format | JSON requests and responses |
| Pagination | Opaque cursor with data and next_cursor |
| Unsafe retries | Optional Idempotency-Key on state-changing routes |
| Rate limit | Per key, with Retry-After on a 429 response |
| Reference | Public OpenAPI 3.1 generated from the application routes |
1. Create a workspace key
In App Workspace Settings, open the Developer tab. Name the key for its workload, choose only the required resource scopes, and optionally set an expiry and source-IP restriction. Owners and admins can create keys; the plaintext secret is shown once.
Use a workspace key beginning ms_sk_ for contacts, sequences, campaigns, enrollments, inboxes, threads, analytics, imports, and webhooks. Organization provisioning keys beginning ms_pk_ are a separate tier and cannot perform routine workspace data operations.
2. Confirm the key identity
curl https://app.mailsequence.com/api/v1/me \
-H "Authorization: Bearer $MAILSEQUENCE_API_KEY"The response identifies the key tier, display prefix, scopes, bound workspace or organization, and rate limit. It never returns the secret or stored token hash.
3. Read a paginated resource
curl "https://app.mailsequence.com/api/v1/contacts?per_page=25" \
-H "Authorization: Bearer $MAILSEQUENCE_API_KEY"Pass the returned next_cursor value as the next request's cursor. Do not interpret or construct cursor values yourself. Collections default to bounded pages and support only the filters documented for that endpoint.
4. Make a retry-safe write
curl -X POST https://app.mailsequence.com/api/v1/contacts \
-H "Authorization: Bearer $MAILSEQUENCE_API_KEY" \
-H "Idempotency-Key: contact-ada-example-001" \
-H "Content-Type: application/json" \
-d '{"email":"ada@example.com","first_name":"Ada"}'Reuse an idempotency key only for the same request and body. A replay returns the stored result. The API rejects the same key when the content changes.
5. Handle errors as part of the client
- 401: missing, malformed, unknown, expired, or revoked credential.
- 403: valid key with the wrong tier, missing scope, or disallowed source IP.
- 404: resource absent inside the key's tenant; foreign-tenant records are not exposed.
- 409: the requested state transition conflicts with current state.
- 422: request fields failed validation.
- 429: wait for the response's
Retry-Afterinterval before trying again.
What can be automated
The v1 surface covers contacts, sequences, campaigns, enrollments, credential-free inbox metadata, threads and messages, daily analytics, bulk imports, webhook endpoints, and agency provisioning. It does not provide GraphQL, a real-time streaming data plane, or any API route that removes recipient suppression.
Sources and product basis
- MailSequence public API reference
Generated endpoint, schema, filter, scope, and response contract. - MailSequence OpenAPI 3.1 document
Machine-readable version of the current public contract. - MailSequence developer platform
Resource coverage, key tiers, safety model, webhooks, and MCP.