Minutemailer API

Use the Minutemailer API to create, update and delete lists and contacts from your app.

To use the API you need an API token. Create a free account on Minutemailer and go to your API settings page to create a token.

You can also use our ready made libraries to implement the API quick and easy. Right now available for PHP. More coming soon.

The API is located at api.minutemailer.com/v1

Overview

Function HTTP method Endpoint
Get all contact lists GET /contactlists
Create contact list POST /contactlists
Get a single list GET /contactlists/{_id}
Update a contact list PUT /contactlists/{_id}
Delete a contact list DELETE /contactlists/{_id}
Add a subscriber to a list POST /contactlists/{_id}/subscribe
Unsubscribe one or more contacts POST /contactlists/{_id}/unsubscribe/{_contact-id}
Get all contacts from a list GET /contactlists/{_id}/contacts

Example

Your API token (bearer) must be included in all requests through a Authorization header. A simple request can look like this:

curl -i -H “Accept: application/json” -H “Authorization: Bearer {token}” https://api.minutemailer.com/v1/contactlists

Error handling

Appropriate error codes will be returned for all requests along with a message if available. Successful requests will be responded with a 2xx status code along with a JSON body that varies depending on the endpoint (see examples below).

Get all contact lists

Endpoint

GET /contactlists

Parameters

Name Type Description Default
take integer Number of lists to return 10
skip integer How many lists from the beginning to skip 0
order string The column to order by. Can be created_at, updated_at or name created_at
direction string Sorting direction, desc or asc desc

Response

{
  “contact_lists”: [
    {
      “_id”: “string”,
      “name”: “string”,
      “created_at”: “string”,
“updated_at”: “string”, “status”: “integer” } ], “num_rows”: “integer” }

Create contact list

Endpoint

POST /contactlists

Arguments

Name Type Required
name string Yes

Response

{
  “_id”: “string”,
  “name”: “string”,
  “created_at”: “string”,
  “updated_at”: “string”,
  “status”: “integer”
}

Get a single list

Endpoint

GET /contactlists/{_id}

Response

{
  “_id”: “string”,
  “name”: “string”,
  “created_at”: “string”,
  “updated_at”: “string”,
  “status”: “integer”
}

Update a contact list

Endpoint

PUT /contactlists/{_id}

Argument

Name Type Required
name string Yes

Response

{
  “message”: “string”
}

Delete a contact list

Endpoint

DELETE /contactlists/{_id}

Response

{
  “message”: “string”
}

Add a subscriber to a list

Endpoint

POST /contactlists/{_id}/subscribe

Arguments

Name Type Required
name string No
email string Yes

Response

{
  “message”: “string”
}

Unsubscribe one or more contacts

Endpoint

POST /contactlists/{_id}/unsubcribe/{_contact-id}

Response

{
  “message”: “string”
}

Get all contacts from a list

Endpoint

GET /contactlists/{_id}/contacts

Parameters

Name Type Description Default
take integer Number of lists to return 10
skip integer How many lists from the beginning to skip 0
order string The column to order by. Can be created_at, updated_at, email or name created_at
direction string Sorting direction, desc or asc desc
status string Can be either subscriber or unsubscribed. Omit to include contacts with all statuses.

Response

{
  “contacts”: [
    {
      “_id”: “string”,
      “name”: “string”,
      “email”: “string”,
      “origin”: “integer”,
      “status”: “integer”,
      “uninteracted_emails”: “integer”,
      “created_at”: “string”,
      “updated_at”: “string”
    }
  ],
  “num_rows”: “integer”
}

If you look for more ways of integrating with Minutemailer you can read more on our developer page.

Guides & How-to

Start free account