End Point
https://app.feedblitz.com/f/?TxnMailParameters 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.
Parameters
Required Parameters
You must specify all the required parameters from the provisioning API call. These are:
- apikey
- license
- support
If the license is unknown it will be auto-provisioned. If you have multiple products / bundles, we recommend that you always specify the product parameter.
In addition, the following parameters are required:
| Parameter | Remark |
| The recipient’s email address | |
| From | The sender’s email address |
| Subject | The email’s subject line |
Finally, you must specify at least one of the following parameters:
| Parameter | Remark |
| HTML | The HTML part of the email |
| Text | The Text part of the email |
You may specify both parts if you wish. If an HTML part is specified, then the transactional email API will derive a text version automatically for you. If you only specify a text part, no HTML will be generated (so specifying markdown text will not generate equivalent HTML).
Plain text emails do not enable open tracking, so we strongly recommend that you provide very simple, unstyled HTML for “plain text”emails in such cases.
Optional Parameters
| Parameter | Remark |
| cc | A semi-colon delimited list of email addresses to CC. No more than 10, and no more than 45 characters per address. Addresses specified in the CC field are not searchable in analytics, but are shown in any results. |
| bcc | A semi-colon delimited list of email addresses to BCC. No more than 10, and no more than 45 characters per address. Addresses specified in the BCC field are not searchable in analytics, but are shown in any results. |
| toname | The name (e.g. “Philip”) for the recipient. |
| fromname | The friendly name (e.g. “Lisa”) of the sender. |
| replyto | The email address that will get the reply to this email (includes out-of-office autoresponders). If not supplied, the From address is used by default. |
| id | An ID you supply, opaque to FeedBlitz, which can be used later for analytics. e.g. an SKU number, or HTTP referer (sic) – not sent to the recipient. |
| tags | Track the class or category of email e.g. “Password reset” or “Digest” – not sent to the recipient. |
| filename | File name(s) of files to attach (see remarks). Max 512 bytes. |
| filedata | Data for file attachment(s), default limits are 1MB per file and 1MB for all attachments in total. |
| debug | Set to 1 to append the time stamp to the subject line. |
| privacy | Override the standard privacy URL with this one. The privacy URL must be properly structured, routable and use a hostname (i.e. not IP address octets) |
| readreceipt | If set to “1” will request that the receiving system(s) send a notification to the sender’s email address that the email has been read. Compliance with his request is optional; a receiving system may elect to ignore it. |
| deliveryreceipt | If set to “1” will request that the receiving system(s) send a notification to the sender’s email address that the email has been successfully delivered. Compliance with his request is optional; a receiving system may elect to ignore it if the email has not been bounced. |
File Attachments
Multiple files may be optionally attached.
Binary files MUST be sent as base 64 encoded text, with the string “data:base64,” (without the quotes and including the comma) appearing before the base 64 encoded file data.
Text files MAY also be sent base 64 encoded, using the same scheme.
A simple implementation can choose to base 64 encode every attached file (prepending “data:base64,” of course) and be done, as this removes the burden from your, the developer, of having to decide whether an attachment is binary or not.
Specify multiple attachments by repeating the filename and filedata parameters, one pair per attachment. The number of filename and filedata parameters must match, and file names SHOULD specify a useful standard extension, such as .csv. If specified, the parameters must not be empty.
File attachments larger than 1MB or file names longer than 512 bytes will cause sending to fail unless your account has been granted access to larger file sizes by FeedBlitz. If the size of all the attachments exceeds your account limits (default 1MB), the mailing will fail.
Attached file data is temporarily persisted in the FeedBlitz database for up to seven days, otherwise you are responsible for persisting that data if necessary. File names are saved as part of the mailing metadata, as comma delimited values, and can be retrieved by the reporting functions.
Attachments are subject to anti-virus scanning before being sent. In the event that malware is detected the email will not be sent, and the API will report a failure.
CC and BCC
It’s important that these fields (particularly BCC) are not abused. FeedBlitz tracks metrics and will take action against end users or API partners where mailing quality is poor. In particular, the transactional API is not to be used as a way to perform bulk mailings.
Remarks
The API will return an XML snippet of the following form:
<txnApi>
<rsp stat="ok">
<success code="0" msg="244f4476-c7b7-11e7-91e7-a0a8cd7c058c"/>
</rsp>
</txnApi>The stat attribute will be one of “ok”, “fail” or “warn” with an appropriate message in the msg attribute of the inner <success>, <warn> or<fail> element.
For emails that are successful, the msg attribute of the success element contains a UUID for that specific mailing, which can then be used later for diagnostics or reporting purposes. We strongly recommend that the sent mail ID be logged or persisted in your own systems in the event of a support case relating to the email.
The code attribute has meaning for FeedBlitz tech support, and will typically be zero for successes and -1 otherwise. Failures will be logged at FeedBlitz for up to a week for tier 2 support purposes.
If the stat attribute is “fail” the call did not succeed. A “warn” indicates that something might or might not have worked as expected, and the message text should be reviewed.
Performance
In order to let you know as quickly as possible whether the call worked, parameter validation (including anti-virus scans and validation of email addresses against our blacklists) can take time. Large files will need longer to process, as will larger emails. While we track performance and endeavor to make our best efforts, we suggest that you allow longer than typical time-outs when making API requests.
We also suggest logging failures on your side for diagnostic and analytics purposes. We have learned that, for example, some hosting services will track bandwidth and may throttle your ability to each the API if you breach your bandwidth limits. If you’re not on an unlimited bandwidth host you should track your usage and determine how use of this API might affect it.
Finally, unless there is a separate contract, remember that all FeedBlitz’s services are best effort only, and governed by our site’s overall terms of service.