The resource for a mailing list and its associated article source for RSS updates (automatic campaigns) is called a “syndication” for, well, historical reasons.
In the current FeedBlitz user interface the notion of the syndication was split, into distinct list and campaign concepts. This is easier for users to understand, with each UI component changing different values of the same syndication object.
Core resource path: /syndications
Returns data about the user’s current published syndications, or an empty <syndications /> tag. If a syndication is found, comprehensive information is provided (including summary subscriber metrics) to avoid further API queries. A summary version is also available (see the “summarizing syndications” section 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> <syndications> <count>1</count> <syndication> <id>33369</id> <publisherid>21</publisherid> <publisheremail>firstname.lastname@example.org</publisheremail> <name>FeedBlitz Widgets</name> <description>FeedBlitz Widgets a test feed</description> <link>http://foo.com/foo/atom.xml</link> <created>2006-02-24 23:03:11 -0500</created> <status>ok</status> <liststatus>ok</liststatus> <turbo /> <uid /> <pwd /> <notifyowner>1</notifyowner> <tease>Read the whole entry</tease> <entrylength /> <keepprivate>1</keepprivate> <type>Atom 1.0</type> <linktrack>0</linktrack> <opentrack>0</opentrack> <isauto>0</isauto> <autoresponderid>0</autoresponderid> <validationquestion /> <validationfail /> <includetags /> <excludetags /> <excludeifboth /> <addcomments>0</addcomments> <forwardemail>1</forwardemail> <timezoneid>35</timezoneid> <dynacontent> <id>103</id> <type>0</type> <providerid>2</providerid> <value>pub-xxx</value> </dynacontent> <dynacontent> <id>140</id> <type>1</type> <providerid>4</providerid> <value>UA-xxx-1</value> </dynacontent> <subscribersummary> <subscribers status="deleted">2</subscribers> <subscribers status="ignored">1</subscribers> <subscribers status="ok">3</subscribers> </subscribersummary> </syndication> </syndications> </feedblitzapi>
|<count>||Number of <syndication> objects in a <syndications> block|
|<id>||The syndication’s unique FeedBlitz ID|
|<publisher>||The subscriber ID of the publisher (blank if anonymous)|
|<publisheremail>||The publisher’s email address (or “anonymous”)|
|<name>||The name of the feed as defined to FeedBlitz.|
|<description>||The description of the content as defined to FeedBlitz.|
|<link>||The URL polled by FeedBlitz for automatic (RSS to email) campaigns|
|<created>||Timestamp when the feed was added to FeedBlitz|
|<status>||The feed’s current status (ok / paused / deleted) as set by the owner|
|<liststatus>||The feed’s current system status as of the last poll (e.g. ok / fail)|
|<turbo>||The automated campaign’s schedule frequency, if any. 0 and 1440 indicate daily. -3 indicates On-Demand, -5 Express, -10 ASAP. Other positive values indicate the number of minutes between each poll cycle. e.g. 720 is a 12 hour automated mailing schedule.|
|<uid>||User id if required by the poller for feeds needing authentication|
|<pwd>||Password if required to access an feed needing authentication|
|<notifyowner>||Whether the user wishes to receive (un)subscribe email notifications|
|<tease>||Call to action text if the user is truncating feed content|
|<entrylength>||Maximum # of characters of an entry. If 0, only headlines are sent by default (the template may override this using a template shortcode).|
|<keepprivate>||(Deprecated) Do not show in FeedAdvisor results or other public places|
|<type>||Type of feed at create time. Not updated by the system as feeds change, and so not to be relied upon.|
|<linktrack>||1 if the user wishes to track click-throughs|
|<opentrack>||1 if the user wishes to track email opens|
|<isauto>||1 if this syndication is used as an autoresponder / funnel / drip campaign|
|<autoresponderid>||The ID of the list this feed uses as an funnel campaign for new subscribers|
|<validationquestion>||User must confirm this text for a subscription to succeed on classic subscription forms|
|<validationfail>||Text to present if the user does not confirm the verification|
|<subscribersummary>||Block of tags summarizing subscriber info for this feed|
|<includetags>||Comma separated list of tags to include in the email|
|<excludetags>||Comma separated list of tags which should not be in the mail|
|<excludeifboth>||By default, if an include and exclude tag are present, the post is included. This is “1” if the post should be excluded.|
|<addcomments>||1 if the user has comments links added to their outbound emails.|
|<forwardemail>||1 if the user has “email to a friend” enabled in the outbound emails.|
|<timezoneid>||The time zone ID of the feed; used to determine the time and scope of a “nightly” run. See the time zones resource.|
|<dynacontent>||(Deprecated) Automatically inserted content for ads and site metrics.|
|<subscribers status=”XYZ”>||Count of subscribers with the status XYZ.|
The <subscribers> summary tag only shows the # of subscribers present. So if there are no pending registrations there will be no <subscribers status=”pending”> entry (as is the case in the example record above). Note that the <subscribers> tag here is not the same as the <subscribers> resource documented elsewhere. If the caller requires complete subscriber information they can access the appropriate /subscribers resource for the relevant syndication(s).
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.
GET – Fetching Syndication Data
Valid paths returning syndication XML are:
|/syndications||Returns all the user’s published feeds|
|/syndications/57||Returns the user’s published feed # 57|
See the subscribers section for additional resource URLs that are syndication-specific.
For some needs, such as presenting a GUI with just the name,description and URL of the syndication, the XML returned by this call is unnecessarily verbose. The caller may reduce the amount of information returned by specifying the “summary=1” in the resource URL that they GET or POST to. An example is:
When the API sees a summary flag associated with a request for a syndication resource, the returned XML is reduced to the following:
<?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> <syndications> <count>1</count> <syndication> <id>33369</id> <name>FeedBlitz Widgets</name> <description>FeedBlitz Widgets a test feed</description> <link>http://foo.typepad.com/foo/atom.xml</link> <status>ok</status> <liststatus>ok</liststatus> <turbo>1440</turbo> <subscribersummary> <subscribers status="deleted">2</subscribers> <subscribers status="ignored">1</subscribers> <subscribers status="ok">3</subscribers> </subscribersummary> </syndication> </syndications> </feedblitzapi>
This form is simpler and easy to convert to RSS, HTML and OPML. There is no analogous summary operation for subscription resources.
POST – Searching Syndications
Like other resources, Syndications support searching via POST of an XML document to the resource URL:
|<searchpattern>||Performs a literal (i.e. not keyword) search for the specified text in the syndication’s name, description or URL. It is not possible to restrict the search to just the URL, say.|
|<searchstatus>||Returns syndications with that given status. Valid feed status values are: ok fail paused deleted|
|<searchlink>||Searches for an exact match for the URL. Since URL’s are unique to any one user within FeedBlitz, it makes no sense to specify <searchlink> and <searchpattern>.|
|<sort>||Sort the results, if omitted the default sort of list id will be used. You may sort on any tag in the syndication record that does not have child tags, e.g. you may sort on the “created” field but not the “subscribersummary” tag. You may sort on these fields even if you have requested summary results only, when the field itself is not returned in the response XML.|
Specifying multiple search parameters (e.g. both<searchpattern> and <searchstatus>) requires all conditions to be satisfied for a syndication to be returned. You may post a search to a syndication URL with the summary flag enabled; this will return the summary form of the syndication XML resource.
POST – Editing Lists
You may POST syndication information to the relevant resource URL. Dates are stripped out, as are any <subscribersummary> values. Note that changing the information in a syndication changes it for all subscribers, and may also change the appearance of the feed in FeedBlitz sites.
Setting a syndication’s status to “deleted” will stop email updates and removes the list from subscriber’s dashboards. Marking it as “paused” stops emails, but leaves the list in subscriber’s dashboards.
A POST will return the appropriate XML for the selected resource.
DELETE – Deleting Syndications
Deletes the resource, returning the appropriate XML on completion.
PUT – Creating a New Syndication
PUT the appropriate XML data to the /syndications resource. The feed will become immediately available for you to manage via the API or the FeedBlitz.com UI. The account holder will be added automatically as a new subscriber.
IMPORTANT: No autodiscovery or validation is performed on the URL passed to the API. If you wish to perform autodiscovery you should perform that yourself in advance, determine the URL to be added as the link, and then POST it to the API.
If successful, you will be returned the full XML for the new resource. The core element in the returned XML is the ID. The ID is the same value as used in the HTML “FEEDID” input parameter for FeedBlitz signup dialogs and links. You may therefore use this information to dynamically construct a signup dialog yourself without having to use the feedblitz.com GUI.