An autoresponder (AR) – also known as a funnel or drip campaign – is a predetermined sequence of emails (entries) that go out to a subscriber, typically with a fixed time between steps in the sequence, initiated by an event such as:
- Subscribing to the AR directly
- A transaction, such as making a purchase, downloading a white paper or e-book, etc.
- Joining a list that triggers a child AR sequence
Introduction to FeedBlitz Funnels (Autoresponders)
Actions and Conditions
At each point in a sequence, FeedBlitz can
- Perform other tasks at each step in the sequence:
- Add or delete a tag or custom field.
- Jump to a different entry in the sequence instead of the next one.
- Change a subscription to another list at any point in the sequence.
- Fetch a URL.
- Add or drop the subscriber from a group.
- Change the effective start date of the sequence.
- Make performing the task conditional, depending on:
- The value of a tag or custom field.
- Whether a segment expression evaluates to true for that subscriber.
- Whether the subscriber is subscribed to or unsubscribed from a different list.
- Whether the subscriber has opened or clicked inside a given entry in the AR.
- Whether the email is in (or is not in) a group or suppression list.
- Collect metrics on a per-entry and per-subscriber per-entry basis.
A deferment schedule is the ability to tell an autoresponder that it may only send (or more generically, process) an entry:
- On the specified days of the week.
- At the specified time.
- In the specified time zone.
If an entry would be processed but doesn’t match the deferment schedule, then processing (including all actions) is deferred for an hour and then it is checked again. This hourly check repeats until processing is allowed by the deferment schedule, at which point the current entry / entries are processed, and the sequence picks up again.
The default deferment schedule is to have no deferment schedule. In other words, an autoresponder entry may be processed at any time, which maintains backwards compatibility with current autoresponders.
Deferment schedules are currently global to the selected autoresponder (i.e. they apply to all entries in the sequence); may not be overwritten at the entry level; and while multiple days may be selected, only one time may currently be used.
An autoresponder (called a funnel in the FeedBlitz user interface) is an individual list that defines one or more entries in a temporal sequence. Each entry is processed in order as the subscriber progresses through the autoresponder’s sequence. An entry may have one or more actions, and an action may have one or more conditions. If an entry does have more than one condition, all the conditions must be satisfied for that action to be taken (i.e. the condition results are combined with a logical AND).
With these capabilities, it is possible to take different actions and send different messages based on tag (e.g. campaign), field value (e.g. purchase history), create follow-up campaigns or automate list hygiene programs. It is permitted to have AR entries in the sequence that do not send email at all.
Remarks and Restrictions
- There is no default action for entries created via the API. If the entry is to be emailed, the email action must be specified.
- There is no default condition for entries created by the API, which implies that the action is to be taken always.
Managing an AR via the FeedBlitz APIs
The core elements of a FeedBlitz AR are the same as a regular mailing list. You manage an AR’s metadata (e.g. its title) via the /syndications resource. An AR has a <turbo> value of -100, and will also be returned with the <isauto> element have a value of 1.
To create an AR from scratch, you can PUT to the REST API with the appropriate <turbo> value, or create a list using one of the other API methods available, and then POST to the REST API to change the <turbo> value.
The AR API resources described here therefore relate to the entries within an AR, and not the containing autoresponder syndication, accessed via the /autoresponders (plural) resource.
FeedBlitz stores three types of entries: Published (status is “ok”), draft (“draft”) and for entries deleted by the API (“deleted”). Only published entries are evaluated for a subscriber by the autoresponder, and deleted entries are not visible in the FeedBlitz UI. A request for an AR’s entries via the API returns all the relevant entries, no matter what their status.
Funnel / Autoresponder Entry API
Content Resource Paths
/autoresponder/<listid> /autoresponder/<listid>/entries /autoresponder/<listid>/entries/<entryid>
Important: Note that “autoresponder” is singular; a list id is ALWAYS required and that this REST resource refers to a single funnel and its entries. The <listid> is the AR’s list id in FeedBlitz (and is reported by the /syndication or /autoresponders (plural) resource).
You can GET any of the resources listed above. The XML returned varies, depending on the resource requested.
Returns very high level information about the AR’s sequence. Example XML:
<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink"> <autoresponder> <id>634210</id> <deferdays>2,3,4,5,6</deferdays> <defertime>600</defertime> <defertz>20</defertz> <autoresponderentries> <count>8</count> </autoresponderentries> </autoresponder> </feedblitzapi>
A GET of the entries resource: /autoresponder/<listid>/entries provides the entire XML dump of the AR’s entries, e.g.
<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink"> <autoresponder> <id>503829</id> <deferdays>2,3,4,5,6</deferdays> <defertime>600</defertime> <defertz>20</defertz> <autoresponderentries> <count>1</count> <autoresponderentry> <id>672</id> <status>ok</status> <subject>Did you get yours yet? [Free]</subject> <guid>1f96a4a4-0f00-11e5-ad3a-0019998b9c3f</guid> <html><p> <span style="font-family:arial,helvetica,sans-serif;">Hi,</span></p> … </html> <link>http://www.feedblitz.com/f/f.fbz?articles=503829&guid=1f96a4a4-0f00-11e5-ad3a-0019998b9c3f&ajax=4</link> <ordinal>1</ordinal> <delay>2880</delay> <actions> <action> <type>mail</type> </action> </actions> </autoresponderentry> … more entries … </autoresponder> </feedblitzapi>
Note that elements are presented in increasing order of delay and ordinal; i.e. the first entry is the one that will be evaluated first for a new subscriber.
Physical order of actions and conditions is significant. Actions are presented in the order in which they will be taken, first to last, and conditions are presented for each action the same way. It is therefore possible for an action to occur (e.g. apply tag X) that will affect subsequent actions for the same entry (e.g. don’t do this if the subscriber has tag X). FeedBlitz won’t warn you about this class of error. Reordering of actions and conditions via the API is achieved via a POST to the correct resource.
Finally, getting the specific entry XML generates the XML for just that entry within the sequence. e.g. /autoresponder/<listid>/entries/672 yields just that entry.
Deferment Schedule Elements
|deferdays||Comma separated numbers 1 (Sunday) to 7 (Saturday) indicating the allowed days. An empty element (or its absence in a GET) indicates ALL days are allowed (i.e. <deferdays/> and <deferdays></deferdays> and <deferdays>1,2,3,4,5,6,7</deferdays> are all equivalent.). The order of the numbers is inconsequential, and repeated day numbers ignored.|
|defertime||Number of minutes in the time zone when emails should go out. Empty / absent implies any time. FeedBlitz runs autoresponders every hour, so it only makes sense (currently) to use increments of 60. 600 means 10am in the selected time zone. Actual mailing times are approximate and will happen shortly after the specified time. Default is any time, allowed values are 0 (midnight) to 1439 (11:59 pm).|
|defertz||The time zone of the time of day. This is a numeric ID and must match the <id> of the timezone returned by the /timezones resource. The default value is US Eastern, ID 35. If you persist this as a number be aware that it is signed, and that negative IDs exist.|
You can set these values with a PUT or POST to the relevant autoresponder resource, including when you update /autoresponders/<id>/entries
If you combine updating one or more entries with a schedule deferment, and the deferment schedule is OK but the entry action isn’t, be aware that the deferment schedule will update regardless.
It is OK to repeatedly send deferment schedule data to the API even if it hasn’t changed; FeedBlitz will only update its persistent store when a value changes. It is also OK to change on at a time in a post. i.e. you can update the <defertime> element without specifying <defertz> and <deferdays> in your XML payload.
By way of example, these elements specify that the AR can only process actions Monday to Friday at 10am, US Central Time.
<deferdays>2,3,4,5,6</deferdays> <defertime>600</defertime> <defertz>20</defertz>
AR Entry Elements
|id||FeedBlitz assigned ID for the entry. Not editable.|
|status||ok, draft, or deleted.|
|subject||Subject line of email to be sent, if actions allow|
|html||HTML markup for the email to be sent, entity encoded to make the XML valid|
|guid||Unique ID. You may provide / edit this, in which case it is you responsibility to ensure its global uniqueness. If absent, FeedBlitz will provide a GUID.|
|link||Link to a web page associated with the entry, used when formatting the mailing. If blank, FeedBlitz will generate one, which will be a web based version of the html, formatted with the relevant template.|
|ordinal||An integer representing the entry’s position in the sequence. Increasing, but not necessarily monotonically. Not necessarily static; it may change after an AR is saved, either via the API or the UI.|
|delay||The nominal delay (in minutes) from the start of the sequence that this entry should be evaluated after. NB FeedBlitz AR’s are currently processed hourly, so entries separated by less than an hour will likely be processed at the same time.|
|usetemplate||If “0” the AR does not use the AR’s expected template; instead the HTML is sent as is. If <template> is missing it is assumed to be “1” and will use the AR’s setting for the template.|
AR Action Elements
There will typically be one or more <action> elements associated with an entry (the default action for AR’s created via the UI is to always send the email; there is no default action for entries created via the API – you must provide one).
|type||The type of action (See below). Required. The type element must also be the first element if other elements at the action level (i.e. <anycondition> are specified.|
|anycondition||Whether all conditions must be satisfied for the action to take place (the default), or whether any condition being satisfied enables the action. Valid values are empty, 0 (these are equivalent, all conditions must be satisfied, i.e. logical AND), or 1 (any condition being satisfied triggers the action, i.e. logical OR)|
Every <action> has a <type> element. Other elements vary, depending on the <type>. The following types are implemented:
|Sends the <html> email defined for the entry|
|cf||Sets a custom field (“cf”) or tag value.|
|list||Adds to or unsubscribes from a different list in the publisher account|
|jump||Set the next entry in the sequence; overrides the standard temporal delivery.|
|url||Sends an HTTP GET to the specified URL.|
|group||Adds to, or removes, an email address to / from a static group|
Currently the API does not validate action types. If you create an entry with a type other than those specified above, it will be persisted by the API, but will do nothing. It is therefore possible to use custom action types to persist your own information in an action. We strongly advise using a namespace-style declaration of the type (e.g. MegaCorp::App::ActionType) to avoid potential conflicts with future FeedBlitz defined actions. FeedBlitz will never use a namespace-style action type.
The next few sections describe the elements associated with each FeedBlitz action type.
There are no other action elements for the mail type. In other words, the presence of a mail action tells the entry to send the defined email, if the associated conditions permit.
|fieldname||Required: Custom field name or tag to set. NO WHITESPACE.|
|value||Required: The value to set. For tags, this is typically “1” or “0” (w/o the quotes). You may specify an empty value here.|
|tag||Optional: Set to 1 if this is a tag – used when naming a new field|
The <fieldname> you set does not have to have been previously defined by the account. If it is new, then the custom field will be created by FeedBlitz as a hidden field (i.e. not visible to the publisher’s subscribers). If the <tag> element is 1 then the description of the newly created field will be prepended by the text “Tag: ” – otherwise the description of the field will mirror the fieldname. Fieldnames may not have spaces at FeedBlitz, and are case insensitive.
|listid||Required: A List ID to affect. “*” (meaning “all”) is permitted for unsubscribes only.|
|subscribe||Required: 1 – to subscribe, 0 – unsubscribe|
The <listid> must be a list or AR owned by the publisher of the AR requesting the action. If the ListID is specified as “*” (w/o the quotes) AND the action requested is unsubscribe, then the subscriber will be unsubscribed from ALL lists and ARs owned by the publisher on which that subscriber is currently active. The action of unsubscribing to * will remove the subscriber from the autoresponder initiating the request.
Both the subscribe and unsubscribe actions are silent, in that the subscriber is not informed.
If the action is to subscribe a user, and the specified list is an autoresponder, the action will start the target autoresponder sequence (typically this means: send the first email in that sequence, but it actually means: evaluate the first entry and process its actions if that is to be done immediately, i.e. with a delay of zero minutes).
If the action is to subscribe a subscriber, that action will not take place if the subscriber has previously unsubscribed or deleted a prior subscription to the target list. i.e. this action cannot be used to override a previously taken removal.
|entryid||Required: The entry id in this AR that the subscriber should get next|
|delay||Required: The number of minutes from now (i.e. action evaluation time) to delay before the entry is sent|
If the entry exists, the system will ensure that the next entry the subscriber receives will be the one specified after the relevant delay. After that, the subscriber will continue with the time-based sequence from that point forward, unless other jump actions are specified.
So, for example, it is possible to create a continuous weekly email by having an action on the 7th entry jump back to the 1st with a delay of 1440.
It is permitted for an entry to jump back to itself. FeedBlitz will not prevent you from creating infinite loops – in fact it’s a feature, per the weekly AR described above. Absent other actions, the only way to stop such a loop is for the subscriber to unsubscribe.
Note that because FeedBlitz processes autoresponders hourly, jump delays should be at least 60 minutes. Setting a delay less than that risks the destination entry from being missed, in which case the subscriber will be sent the one after that in the temporal sequence after the relevant delay.
|url||Required: The URL to GET|
FeedBlitz will append the following parameters to the URL query string (or add a query string if there isn’t one specified in the URL):
|The email address of the subscriber|
|subid||The subscriber’s ID at FeedBlitz|
|listid||The autoresponder’s list ID|
|entryid||The entry ID of the entry triggering the action|
We recommend, but do not require, SSL for the URL in order to secure the email address of the visitor in flight. FeedBlitz will call the URL exactly once, and will not reattempt the fetch in case of failure.
|groupid||Required: The id of the group|
|join||Required: The action to take. Must be either “join” or “drop” (without the quotes)|
Groups are static collections of email addresses. They can be used to restrict mailings, or to filter bulk subscriber operations. Adding to or dropping an email address is silent; the address is not emailed, nor is any validation or opt-in performed.
An action may have one or more conditions associated with it. When the action is processed, any conditions present will be evaluated for the subscriber. If multiple conditions are specified, they must all be true for the action to take place. If no conditions are present, the action always occurs.
Conditions, when present, are specified within an individual action element as follows:
<action> … action parameters … <conditions> <condition> <type> … </type> … other condition parameters … </condition> </conditions> </action>
Condition XML may also be used in certain other FeedBlitz API operations outside of autoresponder actions. When specified like this, some tags may be specified at the <conditons> level, such as <anycondition>, e.g.
<conditions> <anycondition>0</anycondition> <condition> <type> … </type> … other condition parameters … </condition> </conditions>
The order of conditions is significant; they are evaluated in the order they appear within the XML.
Like actions, every <condition> has a <type> element. Other elements vary, depending on the <type>. The following condition types are implemented:
|tag||Dependency on a tag or custom field|
|expression||Dependency on a custom field segment expression|
|status||Dependency on a subscriber’s status (subscribed, unsubscribed) on a list owned by the account|
|activity||Based on whether the subscriber has opened or clicked an entry in this sequence|
|group||Dependency on whether the subscriber is / is not in a group|
|suppressionlist||Dependency on whether the subscriber is / is not in a suppressionlist|
Currently the API does not validate condition types. If you create a condition with a type other than the ones listed above, it will be persisted, and – when evaluated – unknown condition types will be treated as being TRUE by FeedBlitz. Like actions, it is therefore possible to use custom condition types to persist your own information in a condition. Again, we strongly advise using a namespace-style declaration of the type (e.g. MegaCorp::App::ConditionType) to avoid potential conflicts with future FeedBlitz defined conditions. FeedBlitz will never use a namespace-style condition type.
|fieldname||Required: The custom field name or tag name to use|
|operator||Required: An operator (see below)|
|value||Required: The value to test against|
If the condition <fieldname> <operator> <value> is true, the action may proceed. If the feldname is not found in the publisher’s account, the condition evaluates to false.
The following operators are defined:
|istagged||True if the custom field value stored for the subscriber is not empty|
|isnottagged||True if the custom field value is not stored, or is empty, for the subscriber|
|==||See note after table|
|!=||See note after table|
|<||See note after table|
|<=||See note after table|
|>||See note after table|
|>=||See note after table|
|contains||True if the subscriber’s stored value contains the specified string|
|notcontains||True if the subscriber’s stored value does not contain the specified string|
|startswith||True if the subscriber’s stored value starts with the specified string|
|notstartswith||True if the subscriber’s stored value does not start with the specified string|
|in||The test <value> should be a comma separated list (individual entries will be trimmed of leading and trailing spaces prior to evaluation). True if the stored field value matches one of the entries in the list.|
|notin||Opposite of “in”|
For mathematical logical operators, if both the stored value and the test value are numbers, they are converted to integers and the test performed. If either are a non-numeric string, then the relevant string comparison is performed using C++ semantics (e.g. “Z100” is greater than “Z10”, but “Z20” is less than “Z9”). String comparisons are always case insensitive.
|expression||Required: FeedBlitz custom field (segment) expression|
Evaluates the expression with the full power of FeedBlitz’s segment expression engine. The API will not validate the expression’s correctness. If the expression is itself invalid, the condition is deemed to be false.
|status||Required: One of the following: subscribed, notsubscribed, unsubscribed, notunsubscribed|
|listid||Required: One or more list ids owned by the publisher|
Note that notsubscribed is not the same as unsubscribed, which is why there are four status options. If a subscriber has never subscribed to a list, notsubscribed is true, but unsubscribed is false.
The unsubscribed and notunsubscribed statuses include where a subscriber did not activate a pending subscription, or were moved from the list by the list’s owner (which is stored in the FeedBlitz database as “deleted”).
When multiple lists are specified, the condition is TRUE if the condition (subscribed, not subscribed, etc) is true for ANY of the specified lists.
|event||Required: One of the following: opened, notopened, clicked, notclicked, engaged, notengaged (engaged = opened or clicked)|
|entryid||Optional*: An entry ID on this autoresponder. Either listid or entryid must be specified.|
|listid||Optional*: A mailing list ID. Either listid or entryid must be specified.|
|cycleid||Optional: Restrict activity checks to a specific mailing. Only valid when listid is specified.|
|joinedbefore||Optional: Restrict activity checks to subscribers whose join date (lastupdated) precedes the date or time specified.|
|joinedafter||Optional: Restrict checks to subscribers who joined after The specified date or time.|
|eventafter||Optional: Only true if the open, click or engagement happened after this date or time.|
|url||Optional: The specific URL to check for click / engagement|
For obvious reasons, you should typically test entryids that precede this one in the AR sequence. Note that “clicked” means that the subscriber clicked on any link tracked by FeedBlitz in the entry. It does not track a specific link. This test is useful for list hygiene or follow on campaigns.
All criteria are logical AND; all must be passed for the condition to be true. If both entryid and listid are specified, the listid is ignored and the entry id assumed to belong to the selected AR.
Dates are YYYY-mm-dd, which are taken to mean midnight US eastern on that day. You can specify times as YYYY-mm-dd HH:MM:SS. Times sent in various RFC encodings that include time zone data will be converted to US eastern before processing. (see URL notes for caveats).
eventafter exists to simplify and expedite list cleanups. You can ask for subscribers who joinedbefore <date> and notengaged and eventafter <date>. This eliminates the need to use segment expressions to do this task (and is also considerably faster, as FeedBlitz tracks the last interaction time for each subscriber / list pair). There is no eventbefore entity.
So to track any clicks on an AR, specify this condition, the AR’s listid (not the entryid) and use the clicked event.
Important caveats with URL matches:
- The <url> entity is not case sensitive, but is otherwise an exact match. i.e. http://www.feedblitz.com is not the same as https://www.feedblitz.com is not the same as http://www.feedblit.com/
- Date granularity for URLs is at the day level only, so specifying an eventafter of 2016-02-29 means that the condition will be true if the event happened on March 1st or later
- url matching is not currently available with cycleid precision; it is if the subscriber has ever clicked on the URL. Cycleid is ignored when performing a URL check, but is still used for other checks managed by this condition (so you can specify clicked, cycleid and url, and if the subscriber didn’t click on the mailing at all then the URL check is moot).
- url checks are only performed for clicked, notclicked, engaged and nonengaged events.
- url checking is currently relatively slow. For performance reasons / best practice, specify a URL that is only used in the relevant mailing, in which case you know it’s restricted to a given cycleid anyway. url checking is performed after all other tests and only if all other tests are passed.
|status||Required: One of the following: found, notfound|
|groupid||Required: The group IDs|
The group must be owned by the account. You may specific multiple suppression list IDs to make this condition an OR, as follows:
found = in ANY of the specified groups i.e. IN (A,B,C…X)
notfound = in NONE of the specified groups i.e. NOT IN (A,B,C…X)
|status||Required: One of the following: found, notfound|
|slid||Required: The suppression list’s IDs|
The suppression list must be owned by the account. You may specific multiple suppression list IDs to make this condition an OR, as follows:
found = in ANY of the specified suppression lists i.e. IN (A,B,C…X)
notfound = in NONE of the specified suppression lists i.e. NOT IN (A,B,C…X)
In other words, using the API you can delete the entire AR (which leaves the entries alone; instead it marks the syndication as deleted); or you can delete a single entry, which removes that entry from the published or draft sequence, currently setting the entry’s status to “deleted.”
If you delete a single deleted entry and that entry was the target of pending jumps, the jumps will be reset to use the next entry in the sequence if there is one; the elapsed time will be extended as appropriate. In other words, if the target is entry 2 in the sequence and entry 3 happens 1440 minutes after that, and then 2 is deleted, all the subscribers with pending jumps to 2 will be updated to have pending jumps to 3, and that jump will happen a day (1440 minutes) later than the jump to 2 would have.
If an entry is deleted and there are no others after it in the sequence, subscribers waiting for that entry will be marked as having finished the sequence the next time the autoresponder is processed.
Trying a delete on /autoresponder/<listid>/entries will return an error.
Post edits to one or more entries. You can post to:
/autoresponder/<listid> /autoresponder/<listid>/entries /autoresponder/<listid>/entries/<entryid>
Note: the first two are equivalent.
When you POST, only entries will be affected; use the syndication resource to affect AR metadata.
You should provide the XML that looks like this:
<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink"> <autoresponder> <id>634210</id> <autoresponderentries> <autoresponderentry> <id>672</id> <status>ok</status> <subject>Did you get yours yet?</subject> <html><p>Did you get the free e-book OK?</p></html> <delay>720</delay> <actions> <action> <type>mail</type> </action> </actions> </autoresponderentry> </autoresponderentries> </autoresponder> </feedblitzapi>
The list ID and the entry ID should match the resource path you choose. You may include multiple entries (to the same AR) within a single update, in which case you must POST to one of the first two resource paths.
All fields may be edited with the exception of the Entry ID. For the autoresponderentry elements, you need only supply those entities you wish to change; the others will be fetched from the existing persistent store.
IMPORTANT: If you are using actions and conditions, and you specify an <actions> element, you MUST specify all actions and conditions completely. POSTed actions will completely replace the current data, if specified.
To leave existing actions and conditions unaffected, do NOT include <actions> in your POSTed XML. To remove all existing actions, specify an empty <actions/> (or <actions></actions>) element.
If you change a status, the effect is immediate on all live current subscribers. If the sequence time is extended (via a change in <delay>) it will currently NOT bring back subscribers who are marked as having finished the sequence.
Entry ordinals are recreated by FeedBlitz. However, you may specify an <ordinal> in a POST (and a PUT) to tell FeedBlitz how to order entries that have the same <delay>. You may have multiple entries at the same point in the sequence, and if you want entry ID 987 to be processed before entry ID 123 at the same point in time, then POST to 987’s resource with an <ordinal> less than 123’s. That will achieve the effect you desire. When you next GET the resource, the ordinals will be changed to reflect the desired order of operations. We do not recommend persisting ordinals; instead GET the relevant entry, extract its ordinal, and then POST (or PUT) as appropriate.
Works for any AR resource. You can PUT any of the elements retrieved in a GET, but <id> will be ignored. The following are minimally required: <status> (ok or draft) and <delay> (0 or positive integer). The <link> element must be a valid URL if specified. Otherwise, this is just like a POST. If you specify a mail action but no HTML or subject, FeedBlitz will send a blank email. So make sure your data is complete. The returned XML will have the new entry’s ID if the entry is added, which you can then use and persist as you wish.
Note: There are no uniqueness constraints within FeedBlitz for a new entry within an AR. If you therefore PUT the same entry repeatedly, it will show up multiple times in the AR, with each new entry having a different entry ID.
AR Metrics Resources
Use these resources to access metrics for an autoresponder as a whole, by entry, or for a specific entry, respectively.
/autoresponder/<listid>/stats/<fromdate>/<todate> /autoresponder/<listid>/entries/stats/<fromdate>/<todate> /autoresponder/<listid>/entries/<entryid>/stats/<fromdate>/<todate>
The <listid> is the AR’s list id in FeedBlitz (and is reported by the /syndication or /autoresponders (plural) resource). It is required for all AR operations.
<fromdate> and <todate> are optional. If no dates are specified, the metrics will be retrieved from yesterday (US Eastern). If you only provide a <fromdate>, metrics will be provided for that date only. If you want to specify a given <todate>, you must provide a <fromdate>. The <fromdate> may be the current day, and will retrieve any data stored so far today.
No metrics are available prior to August 22, 2015; the data was not being collected prior to that.
Dates must be provided as YYYY-MM-DD. Metrics are calculated in real time; metrics from the prior day are typically stable and may be persisted locally. You may request data from today’s date.
Only the GET method is supported. The XML returned by the calls is similar 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> <autoresponder> <id>1234567890</id> <stats> <day> <date>2015-08-27</date> <sent>60</sent> <opens>31</opens> <clicks>3</clicks> <unsubscribes>0</unsubscribes> <complaints>0</complaints> <hardbounces>0</hardbounces> <softbounces>0</softbounces> <forwards>0</forwards> </day> </stats> </autoresponder> </feedblitzapi>
If there are multiple days, there are multiple <day> elements, as in the following example:
<?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> <autoresponder> <id>1234567890</id> <stats> <day> <date>2015-08-27</date> <sent>60</sent> <opens>31</opens> <clicks>3</clicks> <unsubscribes>0</unsubscribes> <complaints>0</complaints> <hardbounces>0</hardbounces> <softbounces>0</softbounces> <forwards>0</forwards> </day> <day> <date>2015-08-28</date> <sent>38</sent> <opens>22</opens> <clicks>2</clicks> <unsubscribes>0</unsubscribes> <complaints>0</complaints> <hardbounces>0</hardbounces> <softbounces>0</softbounces> <forwards>0</forwards> </day> </stats> </autoresponder> </feedblitzapi>
<day> elements are returned in chronological order, and a day element will be returned for every day in the date range, so be careful! <day> elements may be empty (apart from the <date>) if there was no activity on that date.
When stats are generated at the entry level, the data XML is presented as follows:
<?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> <autoresponder> <id>1234567890</id> <stats> <day> <date>2015-08-27</date> <autoresponderentry> <id>670</id> <sent>6</sent> <opens>8</opens> <clicks>1</clicks> <unsubscribes>0</unsubscribes> <complaints>0</complaints> <hardbounces>0</hardbounces> <softbounces>0</softbounces> <forwards>0</forwards> </autoresponderentry> <autoresponderentry> <id>672</id> <sent>3</sent> <opens>1</opens> <clicks>0</clicks> <unsubscribes>0</unsubscribes> <complaints>0</complaints> <hardbounces>0</hardbounces> <softbounces>0</softbounces> <forwards>0</forwards> </autoresponderentry> … etc … </day> <day> … </day> … etc … </stats> </autoresponder> </feedblitzapi>
When querying /entries/stats, only entries where there was activity will be displayed for any given day. Entry data will be displayed, if there is data to report, even if that entry has subsequently been deleted or moved back to drafts from the current sequence.
Data for a single entry will be returned looking like this:
<?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> <autoresponder> <id>1234567890</id> <stats> <day> <date>2015-08-27</date> <autoresponderentry> <id>670</id> <sent>6</sent> <opens>8</opens> <clicks>1</clicks> <unsubscribes>0</unsubscribes> <complaints>0</complaints> <hardbounces>0</hardbounces> <softbounces>0</softbounces> <forwards>0</forwards> </autoresponderentry> </day> <day> … </day> … etc … </stats> </autoresponder> </feedblitzapi>
Note that <sent> data is only recorded when the entry’s action includes sending an email, and the conditions are met to permit that email to be sent.