The FeedBlitz Simple API: Adding Subscriptions Programmatically

If you’re a plugin developer, PHP guru, or a web programmer who wants to do more with FeedBlitz but the REST API is daunting, we’re rolling out a new set of features in a “Simple” API that is much easier to use. This API needs an API key, which you can get here after you log in.


Programming Required: Yes
API Key Needed: Yes
Best suited for: Web developer, plugin developer
Skill level: Intermediate
Good for: Adding a subscriber from a popup, plugin, or web site back end


The function of this “Simple” API is to start the FeedBlitz dual opt-in process for a new subscriber, add custom fields along the way, all in a completely programmatic way. Any initial UI (user interface) presented prior to that is the responsibility of you, the developer, to build. This API is email only; it cannot add any of FeedBlitz’s supported social media subscriptions.

The simple API is just a common or garden web page request (an HTTP GET, for the technically minded), as follows:

https://app.feedblitz.com/f?SimpleApiSubscribe&key=<api_key>&email=<email>&listid=<listid>

The following parameters are required:

<api_key>The publisher’s API key, URL encoded
<email>The email you want to add to your list, URL encoded.
<listid>The ID of the list to add the subscriber to.

The list id is displayed on each list’s dashboard, under the list’s title and description.

Additionally, there are optional parameters you can supply to the API, to tag a subscriber and / or add custom fields to their record.

To tag a subscriber, e.g. to add product purchase information, you supply a tags parameter, of the form tags=<taglist> where <taglist> is a comma separated, URL encoded list of tags to apply to the subscriber (tags are added as custom fields, with the value “1”).

To provide custom field data, e.g. names, zip codes, etc., you may optionally provide other parameters in the URL as name / value pairs. The name will be treated as a custom field name, and the value the value to assign to that field for this subscriber. If the custom field doesn’t exist, it will be created.

Examples

Here are some examples, assuming the API key for the FeedBlitz account owning list 84 is “Abc123”, to help show how to use this API:

  1. https://app.feedblitz.com/f?SimpleApiSubscribe&key=Abc123email=phil%40example.com&listid=84Starts the dual opt-in for phil@example.com to list 84.
  2. https://app.feedblitz.com/f?SimpleApiSubscribe&key=Abc123email=phil%40example.com&listid=84&tags=WidgetsStarts the dual opt-in for phil@example.com to list 84, tagging the user with the “Widgets” tag.
  3. https://app.feedblitz.com/f?SimpleApiSubscribe&key=Abc123email=phil%40example.com&listid=84&tags=Widgets,Boxes,StuffStarts the dual opt-in for phil@example.com to list 84, tagging the user with three tags: Widgets, Boxes and Stuff.
  4. https://app.feedblitz.com/f?SimpleApiSubscribe&key=Abc123email=phil%40example.com&listid=84&Name=Phil%20HollowsStarts the dual opt-in for phil@example.com to list 84, and assigns the value “Phil Hollows” to the custom field called “Name”
  5. https://app.feedblitz.com/f?SimpleApiSubscribe&key=Abc123email=phil%40example.com&listid=84&tags=CampaignX&FirstName=Phil&LastName=HollowsStarts the dual opt-in for phil@example.com to list 84, and assigns the value “Phil” to the custom field called “FirstName”, “Hollows” to the “LastName” field, and tags the subscriber with the “CampaignX” tag.

What Happens

If the API call is successful, the API will return list-specific XML and start the dual opt-in process; it is up to the developer using the API to generate the UI update appropriate to their platform to tell the visitor to check their inbox. If unsuccessful, the reason for the failure will be returned in error XML of the form:

<rsp stat=”fail”>
<err code=”-1″ msg=”Specified list not owned by this client account” />
</rsp>

The reason for the failure will be in the msg attribute of the <err> element.

Next up is a post about the REST API. Next week I’ll provide some sample workflows on how to use these APIs in a more-or-less real world example.