Subscription Endpoint | Sign-Up.to Permission Marketing API

Subscription v1.2

Subscriptions link a subscriber to a list. A subscription must be confirmed opt-in before the subscriber can be contacted.

What can I do with subscription?

A subscription is the product of a subscriber giving you their details and permission to contact them. The Sign-Up.to Permission Marketing API is squarely built upon the concept of confirmed opt-in and this is a key part of our terms & conditions.

Attaining confirmed opt-in is the first step to gaining your subscriber's trust and maintaining healthy ROI through your marketing.
You have three choices when it comes to building your confirmed opt-in flow. The simplest is using EmailOptIn to send an email. You can also use our automation and list endpoints to contact the subscriber with an opt-in email, or you can send your own email and report back to us using the confirmed attribute.
Once they have confirmed opt-in, a subscriber must be able to manage which lists they are associated with.
You can clear all subscriptions for a subscriber by filtering subscriber_id when you DELETE. To clear all subscriptions on a list filter by list_id.
A subscriber must have at least one subscription to a list.

We may request proof of every confirmed opt-in which is manually confirmed through the Permission Marketing API.

GET /subscription or /subscription/:id

Attribute	Type	Filter	Sort	Description
id	int	Required*	Yes	Unique ID of the subscription.
confirmationredirect	string	No	No	An optional URL to redirect the subscriber to after they have confirmed their subscription.
confirmed	bool	Yes	No	Whether the subscription has been confirmed via confirmed opt-in. Cannot be set to "false" if value is "true".
list_id	int	Required*	No	Unique ID of the list.
source	enum	No	No	A short descriptor for the source of the subscription: "form", "sms", "api", "import", "automation", "other".
subscriber_id	int	Required*	No	Unique ID of the subscriber.
cdate	decimal	No	Yes	Creation timestamp.
mdate	decimal	No	No	Last modification timestamp.

*At least one of: id, list_id, subscriber_id must always be present.

Subscriptions must be confirmed opt-in before they can be contacted. This is a requirement of permission marketing and our terms & conditions.

HEAD /subscription or /subscription/:id

Attribute	Type	Presence	Description
id	int	Required*	Unique ID of the subscription.
confirmed	bool	Optional	Whether the subscription has been confirmed via confirmed opt-in. Cannot be set to "false" if value is "true".
list_id	int	Required*	Unique ID of the list.
subscriber_id	int	Required*	Unique ID of the subscriber.

*At least one of: id, list_id, subscriber_id must always be present.

POST /subscription

Attribute	Type	Presence	Description
confirmationredirect	string	Optional	An optional URL to redirect the subscriber to after they have confirmed their subscription.
confirmed	bool	Optional	Whether the subscription has been confirmed via confirmed opt-in. Cannot be set to "false" if value is "true".
list_id	int	Required	Unique ID of the list.
subscriber_id	int	Required	Unique ID of the subscriber.

A new subscription will fail if the subscriber is found on your 'Do Not Contact' list or the 'Global Watch List'.

PUT /subscription or /subscription/:id

Attribute	Type	Presence	Description
id	int	Required	Unique ID of the subscription.
confirmationredirect	string	Optional	An optional URL to redirect the subscriber to after they have confirmed their subscription.
confirmed	bool	Optional	Whether the subscription has been confirmed via confirmed opt-in. Cannot be set to "false" if value is "true".

When a subscription is confirmed, any automation rules with 'added to list' actions that reference list_id will be triggered automatically.

DELETE /subscription or /subscription/:id

Attribute	Type	Presence	Description
id	int	Required**	Unique ID of the subscription.
list_id	int	Required**	Unique ID of the list.
subscriber_id	int	Required**	Unique ID of the subscriber.

*DELETE can be issued using id, list_id or subscriber_id. This may result in one or more resources being removed in a single request.

A DELETE will be issued for any subscribers who are left without a subscription. If you are moving a subscriber from one subscription to another, ensure you create the new subscription before removing the old one.

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.

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":                    123456,
    "confirmationredirect":  "http://www.sign-up.to",
    "confirmed":             false,
    "list_id":               543211,
    "source":                "api",
    "subscriber_id":         125543, 
    "cdate":                 12345678,
    "mdate":                 12345678    
}