Contacts

The contacts object is where you handle all of your contacts. That includes email, attributes and which lists the contacts subscribes to.

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

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

Required fields

  • email

Optional fields

  • first_name
  • last_name
  • attributes
  • lists
  • sms_number

Readonly fields

  • url
  • created
  • updated
  • active
  • channels

Example contact

{
    "url": "https://api.getanewsletter.com/v3/contacts/john.doe@example.com/",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "created": "2011-03-14T13:37:12Z",
    "updated": "2013-08-20T04:41:49Z",
    "attributes": {
        "city": "Stockholm",
        "company": "Example Inc."
    },
    "lists": [
        {
            "subscription_cancelled": null,
            "subscription_id": 6982,
            "hash": "hiso7tuNb4Z",
            "name": "My List",
            "subscription_created": "2013-03-26T08:50:30Z"
        }
    ],
    "active": true
}

GET /contacts/

Responds with a list of contacts, 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]>
  • search_email: <string>
  • search_name: <string>
  • lists: <array: string>
  • updated_lt: <string: datetime>
  • updated_gt: <string: datetime>
  • updated_year: <int>
  • updated_month: <int>
  • updated_day: <int>
  • created_lt: <string: datetime>
  • created_gt: <string: datetime>
  • created_year: <int>
  • created_month: <int>
  • created_day: <int>
  • active: <int: 1|0>

Example:

{
    "count": 46,
    "next": "https://api.getanewsletter.com/v3/contacts/?page=3,
    "previous": "https://api.getanewsletter.com/v3/contacts/?page=2,
    "results": [
        {
            "url": "https://api.getanewsletter.com/v3/contacts/john.doe@example.com/",
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "created": "2011-03-14T13:37:12Z",
            "updated": "2013-08-20T04:41:49Z",
            "attributes": {
                "city": "Stockholm",
                "company": "Example Inc."
            },
            "lists": [
                {
                    "subscription_cancelled": null,
                    "subscription_id": 6982,
                    "hash": "hiso7tuNb4Z",
                    "name": "My List",
                    "subscription_created": "2013-03-26T08:50:30Z"
                }
            ],
            "active": true
        },
        ...
    ]
}

POST /contacts/

Creates a new contact. The only required parameter is the email.

Example:

POST /contacts/
{
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "lists": [
        {"hash": "hiso7tuNb4Z"},
        {"hash": "hal332tlgnnf"}
    ],
    "attributes": {
        "city": "Stockholm",
        "company": "Example Inc."
    }
}

Response
{
    "url": "https://api.getanewsletter.com/v3/contacts/john.doe@example.com/",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "created": "2013-08-20T04:41:49Z",
    "updated": "2013-08-20T04:41:49Z",
    "attributes": {
        "city": "Stockholm",
        "company": "Example Inc."
    },
    "lists": [
        {
            "subscription_cancelled": null,
            "subscription_id": 6982,
            "hash": "hiso7tuNb4Z",
            "name": "My List",
            "subscription_created": "2013-08-20T04:41:49Z"
        },
        {
            "subscription_cancelled": null,
            "subscription_id": 6982,
            "hash": "hal332tlgnnf",
            "name": "My Other List",
            "subscription_created": "2013-08-20T04:41:49Z"
        }
    ], 
    "active": true
}
Location: https://api.getanewsletter.com/v3/contacts/john.doe@example.com/

Possible issues / Error message explanation:

You can not confirm the subscription for users that have previously cancelled it. If you do not see this contact as cancelled in your list then it has been deleted after the subscription cancellation.

PUT /contacts/<email>/

Update or create a contact, if a contact doesn't exist it's created.

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

If you change the email you will get a Location header pointing to the new endpoint for this contact.

Example:

PUT /contacts/john.doe@example.com/
{
    "first_name": "John",
    "last_name": "Doe",
    "lists": [
        {"hash": "hiso7tuNb4Z"},
        {"hash": "hal332tlgnnf"}
    ],
    "attributes": {
        "city": "Stockholm",
        "company": "Example Inc."
    }
}

Response
{
    "url": "https://api.getanewsletter.com/v3/contacts/john.doe@example.com/",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "created": "2013-08-01T13:17:33Z",
    "updated": "2013-08-20T04:41:49Z",
    "attributes": {
        "city": "Stockholm",
        "company": "Example Inc."
    },
    "lists": [
        {
            "subscription_cancelled": null,
            "subscription_id": 6982,
            "hash": "hiso7tuNb4Z",
            "name": "My List",
            "subscription_created": "2013-08-20T04:41:49Z"
        },
        {
            "subscription_cancelled": null,
            "subscription_id": 6982,
            "hash": "hal332tlgnnf",
            "name": "My Other List",
            "subscription_created": "2013-08-20T04:41:49Z"
        }
    ],
    "active": true
}
201 Created
200 Updated

PATCH /contacts/<email>/

Patch is used for partial updates. Use it if you want to update a contact but don't want to overwrite all values.

Example:

PATCH /contacts/john.doe@example.com/
{
    "first_name": "Eric",
    "attributes": {
        "city": "Uppsala"
    }
}

Response
{
    "url": "https://api.getanewsletter.com/v3/contacts/john.doe@example.com/",
    "first_name": "Eric",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "created": "2013-08-01T13:17:33Z",
    "updated": "2013-08-20T04:41:49Z",
    "attributes": {
        "city": "Uppsala",
        "company": "Example Inc."
    },
    "lists": [
        {
            "subscription_cancelled": null,
            "subscription_id": 6982,
            "hash": "hiso7tuNb4Z",
            "name": "My List",
            "subscription_created": "2013-08-20T04:41:49Z"
        },
        {
            "subscription_cancelled": null,
            "subscription_id": 6982,
            "hash": "hal332tlgnnf",
            "name": "My Other List",
            "subscription_created": "2013-08-20T04:41:49Z"
        }
    ],
    "active": true
}

DELETE /contacts/<code>/

Deletes the contact.

Example:

DELETE /contacts/john.doe@example.com/

Response
Status 204 No Content