Subscriber Endpoint | Sign-Up.to Permission Marketing API

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

Attribute	Type	Filter	Sort	Description
id	int	Yes	Yes	Unique ID of the subscriber.
bounce_exists	bool	No	No	Whether this subscriber has ever had a bounced email.
companyname	string/null	No	No	Subscriber's company name.
confirmed	bool/null	No	No	Whether the subscription to the list specified by list_id is confirmed.
contact_exists	bool	No	No	Whether this subscriber has ever been contacted.
country	string/null	No	No	Subscriber's country in ISO-3316-1 format (two character), for example "GB".
county	string/null	No	No	Subscriber's county.
daybirth	int/null	No	No	The day of the month of the subscriber's birthday (1-31).
email	string	Yes	Yes	Subscriber email address.
emailmd5	string	No	No	MD5 digest of the contents of the "email" attribute.
emailsuspended	bool	Yes	No	Whether email delivery to the subscriber is currently suspended.
firstname	string/null	No	No	Subscriber's first/given name.
gender	enum/null	No	No	Either "male" or "female".
housenumber	string/null	No	No	Subscriber's house number.
lastname	string/null	No	No	Subscriber's last/family name.
latestopenip	string/null	No	No	IP address from which the subscriber most recently opened an email.
list_id	int/null/array	Yes**	No	List ID(s) of the list that the subscriber is subscribed to.
monthbirth	int/null	No	No	The month of the subscriber's birthday (1-12).
msisdn	string	Yes	Yes	Subscriber MSISDN (see definition). N.B. This attribute is treated as a string.
postcode	string/null	No	No	Subscriber's postcode.
searchexecute_id	int/null	Yes**	No	Unique ID of a stored searchexecute resource.
smssuspended	bool	Yes	No	Whether SMS delivery to the subscriber is currently suspended.
streetname	string/null	No	No	Subscriber's street name.
subscription_count	int	No	No	Number of subscriptions held by this subscriber.
title	string/null	No	No	Subscriber's title.
town	string/null	No	No	Subscriber's town.
yearbirth	int/null	No	No	The four-digit year of the subscriber's birth.
cdate	decimal	No	Yes	Creation timestamp.
mdate	decimal	No	No	Last 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

Attribute	Type	Presence	Description
id	int	Optional	Unique ID of the subscriber.
email	string	Optional	Subscriber email address.
emailsuspended	bool	Optional	Whether email delivery to the subscriber is currently suspended.
list_id	int/null/array	Optional**	List ID(s) of the list that the subscriber is subscribed to.
msisdn	string	Optional	Subscriber MSISDN (see definition). N.B. This attribute is treated as a string.
searchexecute_id	int/null	Optional**	Unique ID of a stored searchexecute resource.
smssuspended	bool	Optional	Whether SMS delivery to the subscriber is currently suspended.

POST /subscriber

Attribute	Type	Presence	Description
companyname	string/null	Optional	Subscriber's company name.
confirmed	bool/null	Required	Whether the subscription to the list specified by list_id is confirmed.
country	string/null	Optional	Subscriber's country in ISO-3316-1 format (two character), for example "GB".
county	string/null	Optional	Subscriber's county.
daybirth	int/null	Optional	The day of the month of the subscriber's birthday (1-31).
email	string	Required*	Subscriber email address.
firstname	string/null	Optional	Subscriber's first/given name.
gender	enum/null	Optional	Either "male" or "female".
housenumber	string/null	Optional	Subscriber's house number.
lastname	string/null	Optional	Subscriber's last/family name.
list_id	int/null/array	Required	List ID(s) of the list that the subscriber is subscribed to.
monthbirth	int/null	Optional	The month of the subscriber's birthday (1-12).
msisdn	string	Required*	Subscriber MSISDN (see definition). N.B. This attribute is treated as a string.
postcode	string/null	Optional	Subscriber's postcode.
streetname	string/null	Optional	Subscriber's street name.
title	string/null	Optional	Subscriber's title.
town	string/null	Optional	Subscriber's town.
yearbirth	int/null	Optional	The 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

Attribute	Type	Presence	Description
id	int	Required	Unique ID of the subscriber.
companyname	string/null	Optional	Subscriber's company name.
country	string/null	Optional	Subscriber's country in ISO-3316-1 format (two character), for example "GB".
county	string/null	Optional	Subscriber's county.
daybirth	int/null	Optional	The day of the month of the subscriber's birthday (1-31).
email	string	Optional	Subscriber email address.
emailsuspended	bool	Optional	Whether email delivery to the subscriber is currently suspended.
firstname	string/null	Optional	Subscriber's first/given name.
gender	enum/null	Optional	Either "male" or "female".
housenumber	string/null	Optional	Subscriber's house number.
lastname	string/null	Optional	Subscriber's last/family name.
monthbirth	int/null	Optional	The month of the subscriber's birthday (1-12).
msisdn	string	Optional	Subscriber MSISDN (see definition). N.B. This attribute is treated as a string.
postcode	string/null	Optional	Subscriber's postcode.
smssuspended	bool	Optional	Whether SMS delivery to the subscriber is currently suspended.
streetname	string/null	Optional	Subscriber's street name.
title	string/null	Optional	Subscriber's title.
town	string/null	Optional	Subscriber's town.
yearbirth	int/null	Optional	The 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

Attribute	Type	Presence	Description
id	int	Required	Unique ID of the subscriber.

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

Error codes

Code	Subcode	Message	Description
400	6	Subscriber email is on the Do Not Contact list: $email	The 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: $email	The subscriber's email address domain has been found on the company Do Not Contact list.
400	8	Subscriber email is on the watch list: $email	The 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: $msisdn	The 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
}