REST API

⌘K
  2. Home
  4. Docs
  6. REST API
  8. API Reference
  10. Subscribers

Subscribers

Core resource path: /subscribers

/subscribers returns all the subscribers to all the user’s lists. Each subscriber’s XML record includes basic information about the subscriber and the user’s feeds to which they are subscribing.  Here’s an example reply, showing that there is one (<count>) subscriber in this set of resources. This subscriber has two subscriptions from this API user, one to list ID 90291 and one to list 96755.  The subscriber may have subscriptions to other lists; they are not shown to this caller.

<?xml version="1.0" encoding="utf-8" ?> 
<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
  <rsp stat="ok">
  <success code="0" msg="Authorized" /> 
  </rsp>
  <subscribers>
 <count>1</count> 
 <subscriber>
 <id>21</id> 
 <email>phil@hollows.com</email> 
 <status>ok</status> 
 <count>2</count> 
 <subscription>
 <id>90291</id> 
 <name>CNN.com</name> 
 <description>CNN.com delivers up-to-the-minute news and information on the latest top stories, weather, entertainment, politics and more.</description> 
 <link>http://rss.cnn.com/rss/cnn_topstories.rss</link> 
 <created>2006-08-21 11:37:38 -0500</created> 
 <updated>2006-08-22 09:56:51 -0500</updated> 
 <status>unsubscribed</status> 
 <liststatus>ok</liststatus> 
 <referer /> 
 <ip /> 
 </subscription>
 <subscription>
 <id>96755</id> 
 <name>CNNMoney.com</name> 
 <description>From CNN and Money magazine, CNNMoney.com combines business news and in-depth market analysis with practical advice and answers to personal finance questions.</description> 
 <link>http://rss.cnn.com/rss/money_topstories.rss</link> 
 <created>2006-08-21 11:37:38 -0500</created> 
 <updated>2006-09-06 16:52:28 -0500</updated> 
 <status>ok</status> 
 <liststatus>ok</liststatus> 
 <referer>http://foo.com/f/f.fbz?NewList</referer> 
 <ip>65.96.75.0</ip> 
 </subscription>
</subscriber>
  <subscribers>
</feedblitzapi>

Note that each resource class contains a <count> of the number of resources it contains; this is to simplify API uses that present summary information.  In the above sample there are two <count> tags.  The first indicates that the <subscribers> block contains 1<subscriber>, and the second that the <subscriber> block contains two <subscription> elements.  Note that there is a <subscribers> (plural) block containing one or more<subscriber> (singular) entries.

Element Comment
<id>The subscriber’s unique identifier in FeedBlitz.  If the subscriber has elected to be anonymous, this will be an empty <id /> tag.
<email>The subscriber’s current email address.  If the subscriber has elected to be anonymous, this value will be “anonymous” and not a valid email address.
<status>The subscriber’s current system status.

<subscription> resources are fully described in the subscription section below.

GET – Fetching Subscriber Information

Valid resource paths that return subscriber XML are:

Path Comment
/subscribersReturns all the user’s subscribers and subscriptions
/subscribers/124All subscriber # 124 subscriptions
/syndications/57/subscribersReturns all the subscribers to feed 57
/syndications/57/subscribers/124Subscriber 124’s subscription to feed 57

If you request a resource that does not exist (say subscriber 124 does not actually subscribe to your syndication 57) you will be returned an empty <subscribers /> tag. 

You can add the following URL parameters when you use GET:

Limitstart, limitcount, summary and since.

  • Use summary=1 for better response times and abridged information.
  • Limit count restricts the number of returned subscriptions
  • Limit start determines the offset for the returned results
  • Provide a date for since (form YYYY-MM-DD) and only changes since that date will be returned.

POST – Searching and sorting subscribers

You may POST to a subscriber URL replacing the subscriber ID with the word “search” to scan the user’s subscriber database, as follows:

Path Comment
/subscribers/search Search all subscribers
/syndications/57/subscribers/search Search subscribers to feed 57

XML is posted to the resource to indicate the search and sort parameters, as follows:

<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
<searchpattern>foo</searchpattern>
<searchstatus>undeliverable</searchstatus>
<sort order="desc">email</sort>
<limitstart>250</limitstart>
<limitcount>500</limitcount>
</feedblitzapi>

You can also specify these parameters in the query string for the resource URI.

Element Comment
<searchpattern>Performs a literal (i.e. not keyword) search for the specified text in the subscriber’s email address.
<searchstatus> Returns subscribers with that given status.
<sort>Sorts by the specified field.  Specify “desc” as the order attribute to sort backwards; otherwise sorts will be returned in ascending order regardless.  The default sort is by subscriber id.  Valid sort values are:
– id (sort by subscriber id);
– email (sort by email address);
– status (sort by subscriber’s system status);
– created (sort by subscription create date);
– updated (sort by subscription updated date).
<limitstart>Only return results from this count forward.  If omitted zero (the beginning) is assumed.  The first row has a row number of zero.
<limitcount> Restrict the number of returned objects this number.  So the example above will return rows 250 to 749 inclusive, if they exist.  Note that the results returned may not return <limitcount> individual subscribers; rather <limitcount> subscriptions are returned. 

Note that when sorting by subscriber fields, all the appropriate subscription data is placed in a single subscriber record – there will be exactly one subscriber record in the returned result set. 

If, however, you sort by a subscription date field (created/ updated) then the subscribers are presented in subscription date order.  There therefore may be multiple <subscriber>blocks for the same subscriber in the returned XML (depending on the search parameters).  It is also possible, depending on the date values, for any one <subscriber> record to have multiple <subscription> records if that subscriber happens to have consecutive subscriptions in the date sorted result set.

If both <searchpattern> and <searchstatus> is specified both conditions must be satisfied (i.e. the search is<searchpattern> AND <searchstatus>).  You may omit or specify empty tags for search parameters you do not care about, so the following is a valid search for all subscriber emails containing “noemail.org”:

<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
<searchpattern>noemail.org</searchpattern>
</feedblitzapi>

The following search returns confirmed subscribers in reverse chronological order, and so could be used to provide “welcome to our newest subscriber” data on a web site.

<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
<searchstatus>ok</searchstatus>
<sort order=”desc”>updated</sort>
</feedblitzapi>

POST – Editing Subscribers

You may POST to change a subscription’s state, with the following restriction: you may not change a subscriber with a deleted, unsubscribed or ignored status.  If you post a field other than status it will be ignored.

You may set the following statuses:

  • deleted
  • archived
  • unsubscribed

In addition, you may set the subscriber to be “ok” if and only if their current status is “archived” – otherwise you may not force a subscriber into an “ok” state from any other status.

If a subscriber is marked as “unsubscribed” or “deleted” only that subscriber can restart their subscription. If a subscriber is marked as “archived” they will not be included in mailings sent to the relevant list. You can however restore them to active status via the API, since the “archived” state is one set by the list owner, not the subscriber, and not FeedBlitz itself.

The following XML sets subscriber 17’s state to “deleted”  

<feedblitzapi version="1.0">
<subscribers>
<subscriber>
<id>17</id>
<status>deleted</deleted>
</subscriber>
</feedblitzapi>

You can use this XML in two ways, removing a subscriber from one or multiple lists in a single operation:

  • To remove subscriber 17 from ALL your syndications, post the above XML to the /subscribers resource path
  • To remove subscriber 17 from syndication 57, post the above XML to /syndications/57

If you wish, you may omit the subscriber number from the XML and post it to the subscriber-specific path as follows (since the subscriber ID is determined by the path):

<feedblitzapi version="1.0”>
<subscribers>
<subscriber>
<status>deleted</deleted>
</subscriber>
</subscribers>
</feedblitzapi>
  • To remove subscriber 17 from ALL your subscriptions, post the above XML to the /subscribers/17 resource path
  • To remove subscriber 17 from syndication 57, post the above XML to /syndications/57/subscribers/17

If an ID is specified in the XML and in the PATH, the ID specified in the PATH will be used.  No warning will be given in the response.

After a POST has been made to edit subscribers, you will be returned the appropriate subscriber XML for resource specified in the path.

DELETE – Deleting a subscriber’s subscription

A DELETE is analogous to a POST setting the status to“deleted” (indicating that you the owner of the list removed the subscriber, as opposed to the subscriber unsubscribing themselves).  You may DELETE in the following resources:

Path Comment
/subscribersDeletes all the subscribers to all your syndications.
/subscribers/17Deletes subscriber 17 from all your syndications.
/syndications/57/subscribersDeletes all the subscribers to syndication 57, but leaves the syndication in place.
/syndications/57/subscribers/17Deletes subscriber 17 from syndication 57

After a delete, you will be returned the XML for the relevant resource.

GDPR – Right to be Forgotten

To remove a subscriber from all lists you control, as well as their PII, in accordance with the GDPR, you use the DELETE end point, setting the status in the XML you send to be “forgotten” as in the following interaction:

DELETE /subscribers/<subscriberid>
<feedblitzapi version="1.0">
<subscribers>
<subscriber>
<status>forgotten</status>
</subscriber>
</subscribers>
</feedblitzapi>

The right to forget call will be logged to your account’s audit trail.

Note that exercising the GDPR right to be forgotten doesn’t prevent future signups by the subscriber to your list(s). However, none of the PII they entered previously will be available to you (nor to them), nor will any history of their prior subscriptions. This call does not affect any PII or subscriptions this subscriber has at FeedBlitz with other list owners (a subscriber may contact FeedBlitz technical support to revoke GDPR permissions for all lists we manage).

IMPORTANT: Exercising the GDPR right to be forgotten applies to all the active lists and funnels in your account the subscriber is or was part of. It also involves physical data deletion, and cannot be undone.

PUT – Adding a new subscriber

You may not PUT to a subscriber resource. 

To create a new subscription you must PUT to the /user resource instead.  See the documentation for the /user resource for important information about starting the subscription process for a syndication (list) that you manage using the API.