All URLs below are simple HTTPS GETs (see, I said it was easy!). Don’t forget to follow the pre-reqs in the introduction.

Configuring the Integration

Get a List of Active Mailing Lists

Your end user must pick the list they want the plugin to add subscribers to. FOr this, we’ll use a quick call to the REST API as follows:

https://app.feedblitz.com/f.api/syndications?key=<api_key>&summary=1

The returned XML will contain one or more <syndication> elements, one for each active list. Grab the <id> and <name> elements within each. You will need to persist the <id> that the user selects.

Important: You must add “text/xml” to your Accept-Type header to make the REST API work.

Get Active Custom Fields / Tags

If the publisher has custom fields and tags defined in their account, it would be nice to offer those on your UI, right? Right! Here’s the REST API call (again, you must have text/xml as an Accept-Type):

https://app.feedblitz.com/f.api/fields?key=<api_key>

The returned XML may contain or more <field> elements. Grab the <name> and the <id> and the <uihidden> elements using your preferred XML parser library.

FeedBlitz allows list owners to create hidden custom fields. Hidden fields can track campaigns, referring pages, etc. Hidden fields should not be displayed to end users (i.e. not shown to site visitors or potential subscribers); it’s obviously ok to show them to the publisher during set up.

If there are no custom fields defined, you can also offer your own (e.g. “Name”). If FeedBlitz finds a new field or tag, it will add that field or tag when you send the data to FeedBlitz at subscription time.

Again, this a REST API call, so be sure to add “text/xml” to your Accept-Type header before accessing the resource.

Save the relevant information and use it to build the user interface you want to present to site visitors.

Subscribing the Visitor

With the configuration all done, potential subscribers will now be using your user interface on the client’s site.

Based on the saved configuration and user-supplied data (and making sure as best you can that the visiting user agent is not a bot – we recommend using <script> to generate your UI on the fly), you then call the simple API to add the subscriber to the list.

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

Optionally add tags and name / value pairs, again as mentioned over here.

To add tags, send a comma separated list in a Tags parameter. Tags are labels applied to the email address associated with the submission.

To add custom fields (name-value pairs), such as 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 for you as a new, hidden, custom field in the FeedBlitz database.

Results

If the ?SimpleApiSubscribe API call is successful, the API will return list-specific XML and start the dual opt-in process; it is up to you 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 by 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.

Single vs Dual Opt-In

If the FeedBlitz client qualifies for, and has enabled, single opt-in, the subscriber will be added immediately, provided that you have specified the X-Forwarded-For header, and that all other aspects of the submission satisfy FeedBlitz’s single opt-in requirements. To coerce dual opt-in, even if the list qualifies for it, simply omit the HTTP header.

Otherwise, a submission will trigger the dual opt-in confirmation process.

Done!

It’s that easy. Two calls to assist in configuration, and one per new subscriber. FeedBlitz handles the entire dual opt-in process from there on, as well as all subscriber management such as bounce handling, unsubscribes etc.