Subscriber v1.2

Add and manage the core data set for a subscriber.

What can I do with subscriber?

Subscribers are at the heart of the Sign-Up.to Permission Marketing API. This endpoint is useful anywhere where you might want to utilise someone's personal details.

  • Subscribers are held within lists, this relationship is called a subscription.
  • Each subscriber must have confirmed opt-in before you can contact them.
  • Add a new subscriber along with their first subscription by including list_id and confirmed attributes.
  • Manage any custom data held against a subscriber with subscriberProfileData and subscriberProfileField.
  • Attributes email and msisdn are unique to a subscriber. These fields can be very useful when filtering.
  • Use contact and bounce to see a subscriber's activity.

GET /subscriber or /subscriber/:id

AttributeTypeFilterSortDescription
id
intYesYesUnique ID of the subscriber.
bounce_exists
boolNoNoWhether this subscriber has ever had a bounced email.
companyname
string/nullNoNoSubscriber's company name.
confirmed
bool/nullNoNoWhether the subscription to the list specified by list_id is confirmed.
contact_exists
boolNoNoWhether this subscriber has ever been contacted.
country
string/nullNoNoSubscriber's country in ISO-3316-1 format (two character), for example "GB".
county
string/nullNoNoSubscriber's county.
daybirth
int/nullNoNoThe day of the month of the subscriber's birthday (1-31).
email
stringYesYesSubscriber email address.
emailmd5
stringNoNoMD5 digest of the contents of the "email" attribute.
emailsuspended
boolYesNoWhether email delivery to the subscriber is currently suspended.
firstname
string/nullNoNoSubscriber's first/given name.
gender
enum/nullNoNoEither "male" or "female".
housenumber
string/nullNoNoSubscriber's house number.
lastname
string/nullNoNoSubscriber's last/family name.
latestopenip
string/nullNoNoIP address from which the subscriber most recently opened an email.
list_id
int/null/arrayYes**NoList ID(s) of the list that the subscriber is subscribed to.
monthbirth
int/nullNoNoThe month of the subscriber's birthday (1-12).
msisdn
stringYesYesSubscriber MSISDN (see definition). N.B. This attribute is treated as a string.
postcode
string/nullNoNoSubscriber's postcode.
searchexecute_id
int/nullYes**NoUnique ID of a stored searchexecute resource.
smssuspended
boolYesNoWhether SMS delivery to the subscriber is currently suspended.
streetname
string/nullNoNoSubscriber's street name.
subscription_count
intNoNoNumber of subscriptions held by this subscriber.
title
string/nullNoNoSubscriber's title.
town
string/nullNoNoSubscriber's town.
yearbirth
int/nullNoNoThe four-digit year of the subscriber's birth.
cdate
decimalNoYesCreation timestamp.
mdate
decimalNoNoLast modification timestamp.

**list_id and searchexecute_id are mutually exclusive.

If searchexecute_id is present, it must refer to a searchExecute resource where store is true and the data stored has not expired (stored data expires 7 days after creation).

If filtering by list_id, subscription_count will be "null" and confirmed will be "true"/"false". For all other filters subscription_count will be an integer and confirmed will be "null".

If your company is restricting access to folders and the user is not an admin, the collection of available subscribers will be constrained to visible subscriptions.

HEAD /subscriber or /subscriber/:id

AttributeTypePresenceDescription
id
intOptionalUnique ID of the subscriber.
email
stringOptionalSubscriber email address.
emailsuspended
boolOptionalWhether email delivery to the subscriber is currently suspended.
list_id
int/null/arrayOptional**List ID(s) of the list that the subscriber is subscribed to.
msisdn
stringOptionalSubscriber MSISDN (see definition). N.B. This attribute is treated as a string.
searchexecute_id
int/nullOptional**Unique ID of a stored searchexecute resource.
smssuspended
boolOptionalWhether SMS delivery to the subscriber is currently suspended.

POST /subscriber

AttributeTypePresenceDescription
companyname
string/nullOptionalSubscriber's company name.
confirmed
bool/nullRequiredWhether the subscription to the list specified by list_id is confirmed.
country
string/nullOptionalSubscriber's country in ISO-3316-1 format (two character), for example "GB".
county
string/nullOptionalSubscriber's county.
daybirth
int/nullOptionalThe day of the month of the subscriber's birthday (1-31).
email
stringRequired*Subscriber email address.
firstname
string/nullOptionalSubscriber's first/given name.
gender
enum/nullOptionalEither "male" or "female".
housenumber
string/nullOptionalSubscriber's house number.
lastname
string/nullOptionalSubscriber's last/family name.
list_id
int/null/arrayRequiredList ID(s) of the list that the subscriber is subscribed to.
monthbirth
int/nullOptionalThe month of the subscriber's birthday (1-12).
msisdn
stringRequired*Subscriber MSISDN (see definition). N.B. This attribute is treated as a string.
postcode
string/nullOptionalSubscriber's postcode.
streetname
string/nullOptionalSubscriber's street name.
title
string/nullOptionalSubscriber's title.
town
string/nullOptionalSubscriber's town.
yearbirth
int/nullOptionalThe four-digit year of the subscriber's birth.

*POST requires either email, msisdn or both.

A new subscriber must be submitted with details of their first subscription. After this point the subscriber and their subscriptions can be managed independently through the appropriate endpoints.

Subscriber records cannot be created if email or msisdn are present in your 'Do Not Contact List'.

Because email and msisdn attributes are unique, a request containing known values will fail.

PUT /subscriber or /subscriber/:id

AttributeTypePresenceDescription
id
intRequiredUnique ID of the subscriber.
companyname
string/nullOptionalSubscriber's company name.
country
string/nullOptionalSubscriber's country in ISO-3316-1 format (two character), for example "GB".
county
string/nullOptionalSubscriber's county.
daybirth
int/nullOptionalThe day of the month of the subscriber's birthday (1-31).
email
stringOptionalSubscriber email address.
emailsuspended
boolOptionalWhether email delivery to the subscriber is currently suspended.
firstname
string/nullOptionalSubscriber's first/given name.
gender
enum/nullOptionalEither "male" or "female".
housenumber
string/nullOptionalSubscriber's house number.
lastname
string/nullOptionalSubscriber's last/family name.
monthbirth
int/nullOptionalThe month of the subscriber's birthday (1-12).
msisdn
stringOptionalSubscriber MSISDN (see definition). N.B. This attribute is treated as a string.
postcode
string/nullOptionalSubscriber's postcode.
smssuspended
boolOptionalWhether SMS delivery to the subscriber is currently suspended.
streetname
string/nullOptionalSubscriber's street name.
title
string/nullOptionalSubscriber's title.
town
string/nullOptionalSubscriber's town.
yearbirth
int/nullOptionalThe four-digit year of the subscriber's birth.

Custom data held against a subscriber can be managed via subscriberProfileData and subscriberProfileField.

DELETE /subscriber or /subscriber/:id

AttributeTypePresenceDescription
id
intRequiredUnique ID of the subscriber.

Also issues DELETE on any subscriberProfileData, subscriptions and pending automation actions which reference the subscriber's id.

Error codes

CodeSubcodeMessageDescription
400
6
Subscriber email is on the Do Not Contact list: $emailThe subscriber's email address has been found on the company/global Do Not Contact list.
400
7
Subscriber email domain is on the Do Not Contact list: $emailThe subscriber's email address domain has been found on the company Do Not Contact list.
400
8
Subscriber email is on the watch list: $emailThe subscriber's email address prefix or domain has been found on the Global Watch List.
400
9
Subscriber MSISDN is on the Do Not Contact list: $msisdnThe subscriber's MSISDN has been found on the company/global Do Not Contact list.
409
13
Subscriber attribute 'email|msisdn' cannot be modified to the value '$email|$msisdn'. Please POST as a new subscriber.If a user makes a PUT request where email or msisdn is set to a value that matches another subscriber's data, but the existing subscriber is not accessible by the user, this error will be returned. In this instance, it will be necessary for the user to POST a new subscriber with the requested email or msisdn.

Please see error handling for more information on error codes.

Examples

Have you seen our example of this endpoint being used with other endpoints?

JSON response

{
    "id":                 87654321,
    "bounce_exists":      false,
    "companyname":        "JSmith Ltd",
    "confirmed":          false,
    "contact_exists":     true,
    "country":            "GB",
    "county":             "Surrey",
    "daybirth":           12,
    "email":              "mailbox@example.com",
    "emailmd5":           "0123456789abcdef0123456789abcdef",
    "emailsuspended":     false,
    "firstname":          "John",
    "gender":             "male",
    "housenumber":        "10",
    "lastname":           "Smith",
    "latestopenip":       "44.131.219.205",
    "list_id":            12345,
    "monthbirth":         3,
    "msisdn":             "447123456789",
    "postcode":           "GU22 7PY",
    "searchexecute_id":   null,
    "smssuspended":       false,
    "streetname":         "Pie street",
    "subscription_count": 3,
    "title":              "Mr",
    "town":               "Woking",
    "yearbirth":          1960,
    "cdate":              1234966741,
    "mdate":              1234966741
}