Contact list management resource#

The contact list resource handles creation, editing, deletion of contact lists and of individual contacts contained within.

Required API Scopes: account_management

Get all contact lists#

The resource results can be filtered using the optional querystring parameters:

filter - all
orderby - one of name, total, lastsenttolist
offset
limit

Request

GET /contact/list?filter=all&orderby=email

Response

{
  "contacts": [
    {
      "list_id": 0,
      "name": "all",
      "lastsenttolist": null,
      "total": "2"
    },
    {
      "list_id": "1",
      "name": "test1",
      "lastsenttolist": "0000-00-00 00:00:00",
      "total": "13"
    }
  ]
  "total": 2,
  "filters": {
    "filter": "all",
    "orderby": "email",
    "offset": 0,
    "limit": 1000
  }
}

Get a single contact list with its recipients#

The resource results can be filtered using the optional querystring parameters:

filter - one of all, subscribed, unsubscribed
orderby - one of email, added
offset
limit

Request

GET /contact/list/{LIST_HASH}?filter=all&orderby=email

Response

{
  "contacts": [
    {
      "recipient_id": "13328313",
      "email": "test1@example.org",
      "added": "2012-10-11 18:03:41"
    },
    {
      "recipient_id": "13134105",
      "email": "test2@example.org",
      "added": "2012-09-05 12:06:13"
    },
  ],
  "name": "all",
  "total": "2",
  "stats": {
    "total": 2,
    "unsubscribed": 0,
    "subscribed": 2
  },
  "filters": {
    "filter": "all",
    "orderby": "email",
    "offset": 0,
    "limit": 1000
  }
}

Get a single contact list in CSV format#

May change in the future to use the `Accept` header

The resource results can be filtered using the optional querystring parameters:

filter - one of all, subscribed, unsubscribed

Request

GET /contact/csv/{LIST_HASH}

Response

Content-type: text/csv
Content-disposition: attachment; filename=listname-filter.csv

email,firstname,lastname,added
email@example.org,John,Doe,2013-01-01 10:00:00
email2@example.org,Jane,Doe,2013-01-01 10:00:00

Get a single recipient from a contact list#

Request

GET /contact/list/{LIST_HASH}/rcpt/{EMAIL}

Response

{
  "contacts": [
      {
        "email": "email@example.org",
        "added": "2012-06-24 07:10:42"
      }
  ]
}

Add contacts with custom fields to contactlist#

If you want to add contacts with custom fields, the contacts can be given as a map of key-value pairs:

Request

POST /contact/list/{LIST_HASH}

Request Body

{
    "name": "Contact list name",
    "contacts": [
        {
            "email": "email@example.org",
            "firstname": "John",
            "lastname": "Doe"
        },
        {
            "email": "email2@example.org",
            "firstname": "Jane",
            "lastname": "Doe"
        }
    ]
}

Response

{
    "status": "created",
    "columns": "3",
    "id": "1"
}

A more compact format which we support is using a definition list. The input can be significantly smaller for large lists.

Request

POST /contact/list

Request Body

{
    "name": "Contact list name",
    "definition": ["email", "name"],
    "contacts": [
        ["email@example.org", "John"],
        ["email2@example.org", "Jane"]
    ]
}

Response

{
    "status": "created",
    "columns": "2",
    "id": "1"
}

Edit an existing contact list#

Add new contacts to an existing contact list. The contacts map supports the same format used for contact list creation, including custom fields. If the contact already exists, the custom fields will be overridden.

Possible action values are:

subscribe
resubscribe
unsubscribe

Request

POST /contact/list/{LIST_HASH}

Request Body

{
    "contacts": ["email@example.org", "email2@example.org"],
    "action": "subscribe"
}

Response

{
    "status": "saved"
}

Manage a single recipient from a contact list#

Edit a contact’s subscription. Possible status values are:

subscribe
unsubscribe

Request

POST /contact/list/{LIST_HASH}/rcpt/{EMAIL}

Request Body

{
    "status": "unsubscribe"
}

Response

{
    "status": "modified"
}