Retrieve a Contact's Publications

Lists every publication in the workspace with this contact's consent state.

POSThttps://api.audienceful.com/v2/people/publications

curl --location --request POST 'https://api.audienceful.com/v2/people/publications' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <your-api-key>' \
--data-raw '{
    "email": "person@example.com"
}'

{
  "data": [
    {
      "id": "kR2xN9mDfLpQ",
      "name": "The Weekly",
      "subscribed": true,
      "explicit": true,
      "source": "api"
    },
    {
      "id": "mZ7bV3nQwXcT",
      "name": "Product Updates",
      "subscribed": false,
      "explicit": false,
      "source": null
    }
  ],
  "unsubscribed_all": false
}

Requires the publications:read scope.

Publications are consent streams — a record of what a contact has agreed to receive. They are separate from audiences, which are about targeting; an actual send goes to the intersection of the two.

This endpoint returns every publication in the workspace alongside this one contact's effective state for each, so a client always sees the full picture rather than only the publications the contact has explicitly touched.

Address the contact in the request body, with either their id or their email. Omitting publications from the body makes the call a read, which is all this endpoint does — add a publications map to the same request to change consent, as described in Update a Contact's Publications.

Body

idstring

The contact's opaque id. Takes precedence over email when both are supplied.

emailstring

The contact's email address (case-insensitive). Use this when you don't hold their id.

One of id or email is required; supplying neither returns a 400.

Also available: `GET /v2/people/{id}/publications`

The path form still works and is not deprecated:

Bash

curl 'https://api.audienceful.com/v2/people/jQKdwqp3YRRtTrwqUJEp7d/publications' \
  --header 'X-Api-Key: <your-api-key>'

Response

dataarray[object]

One entry per publication in the workspace.

Properties

idstring

The publication's id. Use this value as a key when calling Update a Contact's Publications.

namestring

The publication's name.

subscribedboolean

Whether the contact is currently subscribed to this publication. When the contact has made no explicit choice, this reflects the publication's default.

explicitboolean

true when the contact has a deliberate choice on record for this publication (they were subscribed or unsubscribed at some point), false when subscribed is simply the publication's default. This is the difference between "opted out" and "never opted in".

sourcestring or null

How the contact's explicit choice was made, or null when explicit is false.

Values

api

Set through the API.

preference_page

The contact updated their own subscription on a preference page.

form

Set when the contact signed up through a form.

import

Set during a contact import.

manual

A workspace member set it by hand in the app.

one_click

Set via a one-click unsubscribe link.

automation

Set by an automation's subscribe/unsubscribe step.

auto_enroll

Enrolled on creation because the publication auto-subscribes new contacts.

unsubscribed_allboolean

true when the contact has globally unsubscribed from all email. A global unsubscribe outranks every per-publication state, so a contact with subscribed: true on a publication still receives nothing while this is true.

Body

Also available: GET /v2/people/{id}/publications

Response

Also available: `GET /v2/people/{id}/publications`