This resource is for managing the email updates you receive, as opposed to /subscribers which is for managing the recipients of email updates you send.

Core resource path: /subscriptions

Returns data about a user’s subscriptions (i.e. the feeds to which they themselves are subscribing), or an empty <subscriptions />tag.  Information is provided about the subscription itself, but no publisher information is provided in order to protect the privacy of the publisher. Sample XML is below.

<?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>
  <subscriptions>
  <count>1</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>http://www.cnn.com/</referer> 
 <ip>1.2.3.4</ip>
  </subscription>
  </subscriptions>
  </feedblitzapi>

The XML elements have the following meanings:

Tag	Comment
<count>	Number of <subscription> objects in a <subscriptions> block
<id>	The subscription’s unique FeedBlitz ID
<name>	The name of the feed as defined to FeedBlitz.  The feed’s polled XML may be different.
<description>	The description of the content as defined to FeedBlitz.  The polled XML may differ.
<link>	The URL polled by FeedBlitz
<created>	Timestamp when the feed was added to FeedBlitz
<updated>	Timestamp of the last status change (e.g. from pending to ok)
<status>	The feed’s current status (pending / ok / paused / deleted / finished / ignored) as set by the subscriber
<liststatus>	The subscription’s current system status as of the last poll (e.g. ok / fail)
<referer>	The source of the subscription.  This may be: Blank – no referrer was found, or the subscription was added prior to FeedBlitz tracking referrer URLs URL – the referring URL as reported by the user’s client Import: <text> – the subscriber was imported.  The text describes the IP and the FeedBlitz user ID used to perform the import. Autosyndication: <URL> The subscription was added automatically because the user is subscribed to a syndicated OPML (reading list / blogroll) file Autosubscription: <URL> The subscription was added automatically because the user had subscribed themselves to an OPML (reading list / blogroll) file Autoresponder: feedid The subscription is an autoresponder, associated with the specified feed. Note: We retain HTTP’s mis-spelling of the word referrer here, using a single “r”
<ip>	The IP octet of the host creating (not updating) this subscription.  May be blank if the subscription was created prior to FeedBlitz tracking subscription IPs.
<uid>	User ID required to access the URL.  Only returned if you are the owner of the subscription.
<pwd>	Password required to authenticate to the remote URL. Again, only displayed if you are the owner of the subscription.
<includetags>	(Deprecated) Comma separated list of tags to include in the email.  These tags are applied only to posts thatpass the publisher’s tags (if any)
<excludetags>	(Deprecated) Comma separated list of tags to exclude from the email.  These tags are applied only to posts thatpass the publisher’s tags (if any)
<excludeifboth>	(Deprecated) By default, if an include and exclude tag are present, the post is included.  This is “1” if the post should be excluded.  Applies to the subscriber’s tags only, and only to posts filtered in by the publisher’s tags.

It is easy to convert this output using a script or XSL into an RSS feed, HTML page or OPML blogroll for a user based on this output.  For most users there should be no reason to check this content more than daily, unless the caller knows that a subscription change has just been made.

Your app can be notified of subscription changes via a webhook trigger.

GET – Fetching Subscription Information

Valid paths returning subscription XML are:

Path	Comment
/subscriptions	Returns all the user’s subscriptions
/subscriptions/57	Returns the user’s subscription to feed # 57

POST – Searching Subscriptions

Like some other resources, Subscriptions support searchingvia POST of an XML document to the resource URL:

<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
<searchpattern>foo</searchpattern>
<searchstatus>fail</searchstatus>
<searchlink>http://foo.com</searchlink>
<sort order=”desc”>updated</sort>
</feedblitzapi>

Tag	Comment
<searchpattern>	Performs a literal (i.e. not keyword) search for the specified text in the subscription’s name, description or URL.
<searchstatus>	Returns subscriptions with the given status.  Valid feed status values are: ok, fail, paused, deleted
<searchlink>	Searches for an exact match for the URL. Since URLs are unique to any one user within FeedBlitz, it makes no sense to specify <searchlink> and <searchpattern>.
<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 list id.  Valid sort values are: – id (sort by subscriber id); – status (sort by subscriber’s system status); – created (sort by subscription create date); – updated (sort by subscription updated date); – link (sort by subscription URL); – description (sort by the feed’s description).

Specifying more than one search criteria (e.g. <searchpattern>and <searchstatus>) requires that all conditions to be satisfied for a subscription to be returned, i.e. the search is an AND operation.

POST – Editing Subscriptions

You may POST to change a subscription’s state.  The behavior and values you may change with a POST depend on the nature of the subscription you are editing.

• If you are subscribing to a different user’s syndication, only the status will be changed.
• If you are subscribing to your own syndication, you may change the name, link, uid, pwd and status values.  Your syndication will be updated with these values.
• If your subscription is a standalone subscription (i.e. not a list published by a FeedBlitz user), you may change the name, link, uid, pwd and status values.

The XML you post may have multiple <subscription> tags within the single <subscriptions> collection.  In addition, you may operate on the following resources:

Path	Comment
/subscriptions	Changes all your subscriptions as specified in the XML
/subscriptions/123	Changes subscription # 123.

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.

To unsubscribe from a feed, set its status to unsubscribed.

DELETE – Deleting a subscription

A DELETE is analogous to a POST setting the status to “deleted” 

If you  wish to stop receiving updates from a subscription (including one that you are syndicating), you may delete it or POST an “unsubscribed” status to the resource.

You may DELETE in the following resources:

Path	Comment
/subscriptions	Deletes all your subscriptions
/subscriptions/17	Deletes subscription 17

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

PUT – Adding a new subscription

Using PUT creates a new, independent subscription in FeedBlitz for the caller alone.  This method should only be used where there is no existing FeedBlitz syndication (list) for the user to subscribe to.  This is the method used in FeedBlitz.com when a user sets up a new subscription from the FeedBlitz dashboard itself.  This is NOT the method used when the user enters their email address in your signup dialog on your website (that’s the PUT to the \user resource).

So, if you expect more than one user to subscribe to any given feed in FeedBlitz, or you want to syndicate this feed to others, do not use this method. 

Instead, create a new Syndication resource (if necessary)and then PUT to the appropriate /user resource to subscribe the user to it.  This latter approach greatly simplifies management tasks, since updating the subscribers is then simply a matter of changing the relevant /syndication resource, as opposed to having to modify multiple individual distinct subscriptions. Using /syndications also makes all the subscribers to a feed appear in a single location in the FeedBlitz GUI.

If you do need to create a standalone subscription, PUT to this resource.  If you are calling on behalf of a third party client, you should specify the (client) IP and referrer fields if applicable; otherwise the system will attempt to derive them from the runtime environment.

You may PUT any field to the API.  You may omit fields that do not apply, but <name> and <link> are required.  Date fields will be ignored and the actual times inserted.