Introduction: REST API

The Mixmax REST API lets you read and change your data in Mixmax: messages, sequences, templates, meetings, rules and more. It comes with Mixmax plans that include API access; see pricing for which ones. Every request goes over HTTPS to https://api.mixmax.com/v1/.

If you'd like a trial account to use as a developer sandbox, or want to tell us what you're building or what would make the API better, email [email protected].

Authentication

Every request needs an API token in the X-API-Token header:

curl --header "X-API-Token: <your token>" https://api.mixmax.com/v1/users/me

There are two kinds of token:

• A personal API token acts as you, with your access. Create one in Mixmax under Settings > Integrations (open), in the API section. It is shown only once, so store it somewhere safe. A personal token works with every endpoint in this reference.
• An admin-managed API key belongs to the workspace. Workspace admins create them under Admin center > API keys, each with a set of permissions such as Read calls (calls:read) or the sequences permissions. These keys currently work only with the sequences, tasks and calls endpoints; the pages for those endpoints say which permission each one needs. Other endpoints refuse them with 403.

Keep tokens out of URLs, code repositories and browsers. To try an endpoint from this reference, paste your token into the Credentials box on its page.

Requests

Send request bodies as JSON with Content-Type: application/json, and accept JSON responses: a request whose Accept header excludes application/json gets 406.

Pagination

Endpoints that return a list return a page of results, usually newest first:

{
  "results": [ ... ],
  "next": "eyIkb2lkIjoiNjYxZWNi...",
  "hasNext": true,
  "previous": "eyIkb2lkIjoiNmFjZmE1...",
  "hasPrevious": false
}

• limit sets the page size. Most lists default to 50 and allow up to 300; each endpoint's page gives its own numbers.
• To get the next page, send the next value back as ?next=. To walk backwards, send previous as ?previous=. Cursors are URL-safe.
• hasNext and hasPrevious say whether more results existed when the page was read. Because lists are newest first, polling with previous picks up items added since.

Fields and expansions

Many list endpoints accept fields, a comma-separated list of the fields to return, for example ?fields=_id,name. Some endpoints accept expand to add detail about a linked resource or a count, for example ?expand=stages. Each endpoint's page lists the values it supports.

Rate limiting

Each user can make 120 requests per minute, counted across all endpoints and tokens. Some endpoints have their own, lower limit on top of that, noted on their page; downloading call recordings, for example, allows 20 per minute.

Every response carries these headers:

Over the limit, you get 429 with a Retry-After header saying how many seconds to wait. The limit is the same for every customer; if it is a problem for what you're building, tell us at [email protected].

Errors

The API uses standard HTTP status codes: 2xx for success, 4xx when the request can't be fulfilled as sent (a missing field, a resource that doesn't exist or that you can't access), and 5xx for errors on our side. Most errors have a JSON body with a message:

{
  "message": "Missing parameter teamIds"
}

A few endpoints answer some errors with an empty body or plain text; their pages say so.

Webhooks

To get events from Mixmax as they happen, see Rules and webhooks and Verifying webhooks.