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>firstname.lastname@example.org</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>220.127.116.11</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.
|<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:
|/subscribers||Returns all the user’s subscribers and subscriptions|
|/subscribers/124||All subscriber # 124 subscriptions|
|/syndications/57/subscribers||Returns all the subscribers to feed 57|
|/syndications/57/subscribers/124||Subscriber 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:
|/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.
|<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.
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:
|/subscribers||Deletes all the subscribers to all your syndications|
|/subscribers/17||Deletes subscriber 17 from all your syndications|
|/syndications/57/subscribers||Deletes all the subscribers to syndication 57, but leaves the syndication in place.|
|/syndications/57/subscribers/17||Deletes subscriber 17 from syndication 57|
After a delete, you will be returned the XML for the relevant resource.
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.