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

AttributeTypeFilterSortDescription
id
intRequired*YesUnique ID of the subscription.
confirmationredirect
stringNoNoAn optional URL to redirect the subscriber to after they have confirmed their subscription.
confirmed
boolYesNoWhether the subscription has been confirmed via confirmed opt-in. Cannot be set to "false" if value is "true".
list_id
intRequired*NoUnique ID of the list.
source
enumNoNoA short descriptor for the source of the subscription: "form", "sms", "api", "import", "automation", "other".
subscriber_id
intRequired*NoUnique ID of the subscriber.
cdate
decimalNoYesCreation timestamp.
mdate
decimalNoNoLast 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

AttributeTypePresenceDescription
id
intRequired*Unique ID of the subscription.
confirmed
boolOptionalWhether the subscription has been confirmed via confirmed opt-in. Cannot be set to "false" if value is "true".
list_id
intRequired*Unique ID of the list.
subscriber_id
intRequired*Unique ID of the subscriber.

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

POST /subscription

AttributeTypePresenceDescription
confirmationredirect
stringOptionalAn optional URL to redirect the subscriber to after they have confirmed their subscription.
confirmed
boolOptionalWhether the subscription has been confirmed via confirmed opt-in. Cannot be set to "false" if value is "true".
list_id
intRequiredUnique ID of the list.
subscriber_id
intRequiredUnique 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

AttributeTypePresenceDescription
id
intRequiredUnique ID of the subscription.
confirmationredirect
stringOptionalAn optional URL to redirect the subscriber to after they have confirmed their subscription.
confirmed
boolOptionalWhether 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

AttributeTypePresenceDescription
id
intRequired**Unique ID of the subscription.
list_id
intRequired**Unique ID of the list.
subscriber_id
intRequired**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

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.

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    
}