About the API

Mailcoach lets you perform multiple actions through a simple, structured application programming interface (API). Let’s help get you started.

On this page:

Make your first request

Use the API to manage subscribers, create campaign drafts, and send transactional emails from any language. Requests go to your team’s domain, for example https://<your-team>.mailcoach.app/api, not the marketing site or dashboard domain.

  1. Open API Tokens in your account settings. The page lists your team’s API URL and domain.
  2. Create a token with All API endpoints permission for this read-only example. Copy it when it is displayed and keep it secret.
  3. Replace the URL and token below with your own values, then request your user details:
MAILCOACH_API_URL='https://<your-team>.mailcoach.app/api'
MAILCOACH_TOKEN='your-api-token'

curl "$MAILCOACH_API_URL/user" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'
{
  "data": {
    "id": 1,
    "email": "john@example.com"
  }
}

See authentication and rate limiting for token permissions and request limits. Keep API tokens on your server; do not put them in browser JavaScript or public repositories.

API Endpoints

Choose the task you want to automate:

The full API reference is generated from our OpenAPI specification. Use it for endpoint schemas and supported operations. These articles explain how to get started and show examples for common tasks.

GET retrieves data. POST creates resources or performs actions such as sending an email. PUT and, where supported, PATCH update resources. DELETE removes resources. Resource URLs generally use UUIDs returned by the API, rather than numeric database IDs. Check each endpoint’s required fields before updating a resource; a PATCH request does not necessarily accept a partial payload.

Responses

Send Accept: application/json on every request, and Content-Type: application/json when sending a JSON body. Successful responses commonly contain a data object or array. Paginated lists also include links and meta; follow links.next until it is null to retrieve all pages. Cloud list endpoints normally return up to 1,000 records per page.

Successful requests can return 200, 201, or an empty 204 No Content response. The transactional send endpoint returns a top-level uuid when the email is stored, rather than a data wrapper. See each endpoint’s response documentation before parsing a response.

Error handling

Check the HTTP status before using the response. Common errors are 401 for missing or invalid authentication, 403 for insufficient permission, 404 for a missing resource, 422 for validation errors, and 429 for rate limiting. Some endpoint-specific failures, including transactional send failures, return plain text rather than JSON.

A validation response may look like this:

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."]
  }
}

Honor Retry-After when a request is rate-limited. Do not blindly retry writes after a network timeout: the first request may already have created a resource or sent an email.