Skip to documentation

About the API

Connect your application to Mailcoach, make your first request, and learn how to handle API responses.

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#

For a first newsletter integration:

  1. Create a list.
  2. Add your own address and confirm it if required.
  3. Optionally, create a template.
  4. Create a draft and send a test.

Sending to the list is a separate final action. For transactional-only integrations, configure your sender, create a Send only token, and start with a fake transactional send.

A UUID is a resource’s unique identifier, such as the string under data.uuid in a list or campaign response. Save the returned value for subsequent requests; your user response’s numeric id is not a list UUID.

Choose the task you want to automate:

These articles explain how to get started. The pages under Endpoints show an example for every endpoint, grouped by resource.

  • 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.