End Point
https://app.feedblitz.com/f/?TxnMetricsParameters may be provided as (HTTP encoded) URL parameters in a GET (total URL length MUST be < 2048 bytes or the GET will fail); or multipart form variables in a POST. If a variable is in both the URL and POSTed form data, the URL parameters take precedence. All parameter names are case insensitive.
Metrics are available for mailings (TxnMetrics), licensing (TxnMetrics=licenses) and billing (TxnMetrics=billing). Billing and license summaries are very similar, except that licensing summarizes by product.
Note that licenses and billing calls return metrics for products and licenses first seen in the specified month; they’re not a running total, and they do not take into account the product or license’s current status.
Metrics are delivered for the current month by default.
Parameters
The following parameters are available for all three forms of the metrics end point.
| Parameter | Remarks |
| apikey | Required. Your transactional mailing API key. |
| license | Restrict results to just this particular license. |
| product | Restrict results to just this particular product name. |
| detail | 1 to show all results as well as the summary. Default: 0. |
| date | Show for the month containing this date (Format: yyyy-mm-dd) |
In addition, the following parameters are available for the mailing metrics call (i.e. plain TxnMetrics):
| Parameter | Remarks |
| exactdate | The default behavior is to show the entire month for the date specified. To facilitate better responsiveness, pagination by day, and more granular analytics, specify exactdate=1 and data will only be returned for the day specified. Gather multiple days’ data by repeating the call with exactdate=1 and a different date specified. IMPORTANT: If you specify exactdate=1 then the XML returned replaces the <month></month> element with a <day></day> element. i.e. instead of (say) <month>2021-05</month> you might get <day>2021-05-21</day> if you specified date=2021-05-21 and exactdate=1 |
| id | Filter by the ID you provided with the email |
| tags | Filter by the tags you provided with the email |
| emailid | Filter by individual email using the email’s UUID given to you by FeedBlitz |
| from | Filter by the sending address used |
| Filter by receiving email address (does not include CC or BCC) | |
| groupby | Summarize results. Valid values for this parameter are one of: id, tags, email, from, product, license |
| summary | Set to 0 to skip production of summary metrics when you are looking for details only. This can dramatically improve the call’s performance if you don’t need aggregate data for the time frame in question. |
| Fields | A comma separated list of entities you want returned, which restricts the returned XML to just those XML entities and <rowid>. html and text entities can be very large, and constructing / sending / receiving / parsing them can be expensive. If you don’t need these entities, we recommend you use the fields parameter to skip them. |
Results are returned as XML. If filters are used they will be noted; there will be one or more elements for each element specified by the groupby parameter. If detail=1 is specified, there will be info elements for each individual element. Unless you use paging (see below), detail results are returned in chronological order i.e. oldest first.
Paging Result Sets
For the simple TxnMetrics call, you can specify limits to improve performance and scale to emulate paging. Every <emailInfo> has a <rowid> associated with it. You can use the following optional parameters to page, based on <rowid>:
| Parameter | Comment |
| startat | Specifies the rowid after which data should be fetched. In other words, the rowid specified will NOT be included in the returned result set. |
| until | The rowid at which the returned results will stop. The specified rowid is NOT included in the returned XML. |
| limit | The number of rows to return |
IMPORTANT: If a paging parameter is detected, the sort order of returned <emailInfo> elements changes to reverse chronological, i.e. newest first.
Usage
To page, start with just the limit parameter. Persist the first and last <rowid>s returned. To continue getting older <emailInfo> elements, specify the startat field to be the last rowid of the prior result set. To refresh a dashboard that might have become stale, use the until parameter using the rowid of the most recent row fetched.
We strongly recommend using summary=0 and the fields parameter to improve performance. You can use date parameters to get detailed history for any applicable time frame.
Billing Results Example (TxnMetrics=billing)
<txnMetrics>
<billingSummary>
<filters>
<product>feedblitz blogger</product>
</filters>
<entry>
<month>2017-11</month>
<newLicenses>4</newLicenses>
<fee>USD 20</fee>
</entry>
<licenseInfo>
<license>d32f5a08-bce9-11e7-9c6e-a0a8cd7c058c</license>
<firstSeen>2017-11-03 12:49:04</firstSeen>
<product>FeedBlitz Blogger</product>
<fee>USD 5</fee>
</licenseInfo>
<licenseInfo>
<license>xyzf5a08-bce9-11e7-9c6e-a0a8cd7c058c</license>
<firstSeen>2017-11-10 14:49:51</firstSeen>
<product>FeedBlitz Blogger</product>
<fee>USD 5</fee>
</licenseInfo>
<licenseInfo>
<license>999f5a08-bce9-11e7-9c6e-a0a8cd7c058c</license>
<firstSeen>2017-11-10 14:53:17</firstSeen>
<product>FeedBlitz Blogger</product>
<fee>USD 5</fee>
</licenseInfo>
<licenseInfo>
<license>321f5a08-bce9-11e7-9c6e-a0a8cd7c058c</license>
<firstSeen>2017-11-11 12:04:27</firstSeen>
<product>FeedBlitz Blogger</product>
<fee>USD 5</fee>
</licenseInfo>
</billingSummary>
</txnMetrics>Email Metrics Results Example
This query (plain old TxnMetrics) had groupby=license specified:
<txnMetrics>
<metrics>
<filters>
<from>phil@hollows.com</from>
</filters>
<entry>
<month>2017-11</month>
<received>8</received>
<sent>8</sent>
<opens>5</opens>
<bounces>1</bounces>
<complaints>1</complaints>
<license>d32f5a08-bce9-11e7-9c6e-a0a8cd7c058c</license>
</entry>
<entry>
<month>2017-11</month>
<received>1</received>
<sent>1</sent>
<opens>0</opens>
<bounces>0</bounces>
<complaints>0</complaints>
<license>xyzf5a08-bce9-11e7-9c6e-a0a8cd7c058c</license>
</entry>
<entry>
<month>2017-11</month>
<received>5</received>
<sent>3</sent>
<opens>1</opens>
<bounces>0</bounces>
<complaints>0</complaints>
<license>999f5a08-bce9-11e7-9c6e-a0a8cd7c058c</license>
</entry>
</metrics>
</txnMetrics>Other fields that may appear in in each include:
| <attachments> | Number of emails with an attachment |
| <ccs> | Number of emails with one or more valid addresses CC’d |
| <bccs> | Number of emails with one or more valid addresses BCC’d |
Performance, Efficiency and Scale
- Avoid detail=1 without providing filters. These datasets can be huge, and the query might time out on you (if it does, retry it).
- Use summary=0 if you don’t need aggregate data.
- Use the fields parameter to filter out potentially large XML elements, such as “html” and “text”
- If searching metrics for a client, find their license ID in your system and apply that as filter; it’s much more efficient than searching on the from address and filtering by product name:
- e.g. I sent email from “Plugin Pro” today to “joe@example.com” – when did he open it? Best API parameters to use: License=xyz1234&email=joe%40example.com&detail=1&summary=0&fields=opened