1. Home
  2. Docs
  3. Transactional API
  4. API Reference
  5. Sending Emails

Sending Emails

End Point

https://app.feedblitz.com/f/?TxnMail

Parameters 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:

ParameterRemark
EmailThe recipient’s email address
FromThe sender’s email address
SubjectThe email’s subject line

Finally, you must specify at least one of the following parameters:

ParameterRemark
HTMLThe HTML part of the email
TextThe 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

ParameterRemark
ccA 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.
bccA 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.
tonameThe name (e.g. “Philip”) for the recipient.
fromnameThe friendly name (e.g. “Lisa”) of the sender.
replytoThe 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.
idAn 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.
tagsTrack the class or category of email e.g. “Password reset” or “Digest” – not sent to the recipient.
filenameFile name(s) of files to attach (see remarks). Max 512 bytes.
filedataData for file attachment(s), default limits are 1MB per file and 1MB for all attachments in total.
debugSet to 1 to append the time stamp to the subject line.
privacyOverride 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)

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.