Subscribers

The subscribers object shows which lists your contacts subscribe to. One contact can have several subscriptions. You can add and remove contacts from any given list.

Renders: [application/json, text/html, application/xml]

Parses: [application/json, application/x-www-form-urlencoded, multipart/form-data]

Required fields

  • contact

Optional fields

  • list
  • cancelled

Readonly fields

  • id
  • url
  • contact_url
  • list_name
  • list_url
  • created
  • responders
  • channels

Example subscriber

{
    "id": 57,
    "url": "https://api.getanewsletter.com/v3/lists/hiso7tuNb4Z/subscribers/john.doe@example.com/",
    "contact": "john.doe@example.com",
    "contact_url": "https://api.getanewsletter.com/v3/contacts/john.doe@example.com/",
    "list": "hiso7tuNb4Z",
    "list_name": "My list",
    "list_url": "https://api.getanewsletter.com/v3/lists/hiso7tuNb4Z/",
    "created": "2013-08-26T09:23:47Z",
    "cancelled": null,
    "responders": []
}

GET /lists/<hash>/subscribers/

Responds with a list of subscribers, like usual we provide next, prev, count and the results

Possible url parameters are:

  • page: <int>
  • order: <string: [email, -email, name, -name, updated, -updated, active, -active]>
  • created_lt: <string: datetime>
  • created_gt: <string: datetime>
  • created_year: <int>
  • created_month: <int>
  • created_day: <int>
  • cancelled: <int: 1|0>
  • active: <int: 1|0>

Example:

{
    "count": 46,
    "next": "https://api.getanewsletter.com/v3/lists/hiso7tuNb4Z/subscribers/?page=3,
    "previous": "https://api.getanewsletter.com/v3/lists/hiso7tuNb4Z/subscribers/?page=2,
    "results": [
        {
            "id": 57,
            "url": "https://api.getanewsletter.com/v3/lists/hiso7tuNb4Z/subscribers/john.doe@example.com/",
            "contact": "john.doe@example.com",
            "contact_url": "https://api.getanewsletter.com/v3/contacts/john.doe@example.com/",
            "list": "hiso7tuNb4Z",
            "list_name": "My list",
            "list_url": "https://api.getanewsletter.com/v3/lists/hiso7tuNb4Z/",
            "created": "2013-08-26T09:23:47Z",
            "cancelled": null,
            "responders": []
        },
        ...
    ]
}

POST /lists/<hash>/subscribers/

Creates a new subscriber. The only required parameter is contact. The contact have to exist on your account to be able to create a new subscription.

If you set "cancelled": true the subscription will be cancelled.

Example:

POST /lists/hiso7tuNb4Z/subscribers/
{
    "contact": "john.doe@example.com"
}

Response
{
    "id": 57,
    "url": "https://api.getanewsletter.com/v3/lists/hiso7tuNb4Z/subscribers/john.doe@example.com/",
    "contact": "john.doe@example.com",
    "contact_url": "https://api.getanewsletter.com/v3/contacts/john.doe@example.com/",
    "list": "hiso7tuNb4Z",
    "list_name": "My list",
    "list_url": "https://api.getanewsletter.com/v3/lists/hiso7tuNb4Z/",
    "created": "2013-08-26T09:23:47Z",
    "cancelled": null,
    "responders": []
}
Location: https://api.getanewsletter.com/v3/lists/hiso7tuNb4Z/subscribers/john.doe@example.com/

PUT /lists/<hash>/subscribers/<subscriber_email>/

Update or create a subscriber, if the list doesn't exist it's created.

Status code is 200 if the attribute is updated and 201 if it's created

Example:

PUT /lists/hiso7tuNb4Z/john.doe@example.com/
{
    "cancelled": true
}

Response
{
    "id": 57,
    "url": "https://api.getanewsletter.com/v3/lists/hiso7tuNb4Z/subscribers/john.doe@example.com/",
    "contact": "john.doe@example.com",
    "contact_url": "https://api.getanewsletter.com/v3/contacts/john.doe@example.com/",
    "list": "hiso7tuNb4Z",
    "list_name": "My list",
    "list_url": "https://api.getanewsletter.com/v3/lists/hiso7tuNb4Z/",
    "created": "2013-08-26T09:23:47Z",
    "cancelled": "2014-01-25T03:13:37Z",
    "responders": []
},
201 Created
200 Updated

PATCH /lists/<hash>/subscribers/<subscriber_email>/

Patch is used for partial updates. Since attributes only has one updatable field it has the same effect as PUT.

DELETE /lists/<hash>/subscribers/<subscriber_email>/

Removes the subscriber from the list.

Example:

DELETE /list/hiso7tuNb4Z/subscribers/john.doe@example.com/

Response
Status 204 No Content