Contact list management resource

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

Also see: Contact list resource PHP code samples

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}

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

Response

Status: 201

{
    "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

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

Response

Status: 201

{
    "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}

{
    "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}

{
    "status": "unsubscribe"
}

Response

{
    "status": "modified"
}