These resources enable the API user to send email campaigns to a list (or a segment of a list). The mailing API has two commands, accessible via either PUT or POST, which map directly to the analogous commands in the FeedBlitz user interface. The names for each type of mailing refer to how they were known in early versions of FeedBlitz.

These are all versions of the “Single Email” campaign in the current FeedBlitz user interface.

Newsflash	Send any arbitrary message to the list
OnDemand	Send selected posts from the automatic campaign’s RSS feed
SendMail	Send an email to one ore more identified recipients, tracked as a campaign (effectively, a single subscriber newsflash mailing)

Unlike the user interface, these resources have a <testmode> element, enabling API developers to test their integrations without the risk of sending an email to an active list.

Newsflash

Resource path: /newsflash/<listid>

Send an arbitrary message to the list, or a subset (segment) thereof.

Methods:         GET, PUT, POST, DELETE

GET and DELETE only work for newsflashes scheduled in the future.

GET – Currently Scheduled Mailings

Returns a list of currently scheduled mailings where <listid> is the main list associated with the mailing. Returned XML is of the following form:

<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
  <rsp stat="ok">
    <success code="0" msg="Authorized" />
  </rsp>
  <scheduled>
    <listid>17</listid>
    <count>2</count>
    <newsflash>
      <scheduleid>1234</scheduleid>
      <schedule>2020-05-12 16:07:00 +0000</schedule>
      <subject>A scheduled mailing</subject>
      <status>ready</status>
    </newsflash>
    <newsflash>
      <scheduleid>5678</scheduleid>
      <schedule>2020-05-12 16:08:00 +0000</schedule>
      <subject>A later mailing</subject>
      <status>ready</status>
    </newsflash>
  </scheduled>
</feedblitzapi>

The <schedule> is always in UTC. Available states are:

• ready
• paused (i.e. the mailing is being edited in the UI)
• draft
• starting

Scheduled mailings in the “starting” state cannot be deleted.

PUT, POST – Set up a Mailing

Either PUT or POST works; they are synonyms. There is no difference in the XML sent / returned, nor in their effects.

To send a newsflash, POST or PUT the required XML to the list’s newsflash resource. So, for example, to send a newsflash to list ID 84:

Resource URL:           /newsflash/84

Example Posted XML:

<?xml version="1.0" encoding="utf-8" ?> 
  <feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
  <newsflash>
  <subject>Hello World</subject>
  <message>This & that & the other</message>
  <tags>testing,123,Is This Thing On</tags>
  </newsflash>
  </feedblitzapi>

Tags are converted to a category header in the SMTP envelope for rendering by email clients that support category display.

Tag	Comment
<subject>	Required. Entity encoded subject line.
<message>	Required. Entity encoded HTML message.  Will be formatted using the list’s default template unless the <usetemplate> entity is zero (see below).
<tags>	Optional: Comma separated list of entity encoded categories to send along with the mailing.
<seg_criteria>	Optional: Send to a segment of the list. Contains entity encoded segment expression per FeedBlitz’s standard custom field expression rules. Default is empty, i.e. send to all subscribers.
<testmode>	Optional: When inner text is 1 (i.e. <testmode>1</testmode>) puts mailing in “sandbox” – nothing is sent. Otherwise mailings will proceed (i.e. implied default is 0)
<usetemplate>	Optional: Use to disable processing of the message by the list’s template. (i.e. <usetemplate>0</usetemplate>). Default is 1, i.e. the template will be used. Set to zero when you want the message body to be sent as-is. Markup will always be treated as HTML by FeedBlitz, conversion to a corresponding text part is automatic if a text part isn’t specified.
<textpart>	Optional: Specify the text alternative to the main HTML message to be sent as a text MIME part in the mailing. If none is specified, FeedBlitz will automatically generate a text part from the HTML message.
<suppressionlistid>	Optional: Comma separated list of suppression lists owned by the account. Emails in the suppression lists will not be mailed the content. The list may be followed by a + or a – sign, in which case the value is treated as a ListID. + indicates suppress active subscribers from the specified list, – means suppress unsubscribed.
<fromname>	Optional: Override the list’s settings with this friendly name
<fromaddress>	Optional: Override the list’s settings with this sending address.  This is also the reply-to address.
<conditions>	A set of autoresponder <condition> elements wrapped by <conditions>…</conditions>. See the Autoresponder API for insight into <condition> XML. Set the <anycondition> element at the <conditions> level (i.e. <conditions> <anycondition>1</anycondition> <condition>…</condition> </conditions>) to make the <condition>s evaluate as logical OR instead of logical AND.
<engagement_fn>	Optional: Specifies the level of engagement a subscriber must have had with the list(s) since <engagement_date>.  Valid values are: newbie – subscription created on or after the date. super – sub created on or before the date, subscriber engaged with every mailing sent on or after the date. hot – sub created on or before, engaged with at least 2/3 of mailings sent on or after. warm – sub created on or before, engaged with at least 1/3 of mailings sent on or after. did – engaged with any mailing sent on or after the date. didany – engaged with any mailing sent on or after the date, regardless of when the subscriber joined the list. There are also valid inverse options, whose meaning should be obvious: notsuper, nothot, notwarm, didnot. In the event hot / warm are used, their minimum value is 1 mailing. For example, if 2 mailings happened in the timeframe, super == 2, hot == warm == did == 1. If specified, the <engagement_date> is required to make the parameter take effect. If more than 1 list is used in the mailing, the function is evaluated independently for each list, with each evaluation ADDING to the ultimate list of subscribers. IOW, it’s an OR for all the lists. The engagement date also limits the functionality to people who joined before that date, unless the function is “didany” For example, say a subscriber is on lists A and B, and has not engaged with every mailing sent to A, but has to B. The API call says to use both lists A and B in the mailing and specifies “hot” as the function to use.  The subscriber will be included because they are “hot” on list B. Finally, the engagement list is used to FURTHER FILTER qualifying subscribers specified as <recipients> or who are members of <groups>. So if subscriber X is specified as a <recipient> but fails to meet the engagement criteria, they will not be mailed.  If a group includes emails P, Q, R and S, but only Q and S meet the criteria, then only Q and S will be mailed.
<engagement_date>	Optional: The date used by the <engagement_fn>, specified as YYYY-MM-DD.  This parameter is required when <engagement_fn> is used.
<groups>	Optional: A comma separated list of group IDs owned by the account. If no groups are specified, the email goes to all subscribers on the list(s). Specifying groups restricts the mailing to only those subscribers in any of the specified groups (i.e. the union of all the email addresses in the groups). The selected addresses are then ANDed with other filtering criteria. You can specify any arbitrary email addresses in a group. Only those actively on the list will be mailed (i.e. you cannot use a group criteria to email someone who hasn’t signed up for the list). If you specify groups and no emails in the groups exist as subscribers to the list(s), the email will not be sent to anyone. You can also specify that a group be used as a suppression list – in other words, to say send to everyone on the list except active subscribers in this group. Indicate that a group is to be used this way by appending a trailing tilde (~) character to the group id.
<recipients>	A comma separated list of email addresses that the mailing is to be sent to. Effectively, allows you to use <group> inclusion functionality without having to go to the effort of creating a group.
<otherlists>	A comma separated list of list IDs to include in the mailing, in addition to the list specified in the resource path.  If a subscriber is on multiple lists, the lists will be searched (and the email sent from, metrics applied to, and formatted by) the lists in the following order: The list ID specified in the resource URL, then the list IDs specified by this element in the order specified.
<schedule>	Optional: If omitted, the mailing launches immediately. If present, the mailing will be schedules at the specified date and time, provided that the date and time is in the future. You should specify the date and time with time zone offsets, e.g March 11, 2020 at 5:04pm US Eastern Daylight Time is 2020-05-11 17:04 -0400. If you do not specify a time zone offset, FeedBlitz treats the date and time as if they are UTC. Important: – Seconds are ignored and set to 00 – The schedule you want might not be available, in which case the scheduled time will be moved to be later (and is present in the returned XML along with a warning status message)
<remail>	Identifies that this is a follow-up mailing. See later in this doc for information about the <remail> XML.

Subject, Message, tag and seg_criteria elements must be entity encoded. The API does not check for validity in the HTML send in the body; it will simply format and send the content you define.

IMPORTANT: Once a mailing starts it cannot be stopped.

With test mode enabled no activity will occur but the API will report a success in the response along with a warning that test mode is on.

The returned XML gives the mailing ID of the campaign if it launched successfully in the following form, for a mailing that launches immediately:

<newsflash>
  <mailingid>1234</mailingid>
</newsflash>

If you schedule a mailing, XML of the following form is returned when the process is successful:

<newsflash>
  <scheduleid>1234</scheduleid>
  <schedule>2020-05-11 21:04:00 +0000</schedule>
</newsflash>

• The returned schedule date and time is always in UTC.
• If the time had to be moved because a scheduled mailing to this list already existed, the time will represent the closest time after the date you requested FeedBlitz has available.
• Scheduled mailings may start up to a minute before the scheduled date and time.
• You can use the persisted <scheduleid> to delete a scheduled mailing via the DELETE method (see below).

Attachments

The single email campaign (newsflash resource) API allows attachments to be sent to recipients. There may be at most 10 attachments per mailing, and the total size of all files sent must not exceed 1MB. Sending binary files (including compressed archives) is permitted, subject to anti-virus scans.

Attachments are specified by including an <attachments> element within the <newsflash> XML, as in the following example:

<attachments>
  <attachment>
    <filename>test/abc.txt</filename>
  </attachment>
  <attachment>
    <filename>helloworld.txt</filename>
    <filedata>SGVsbG8gd29ybGQh</filedata>
  </attachment>
  <attachment>
    <filename>group.txt</filename>
  </attachment>
</attachments>

There must be one or more <attachment> entry within <attachments>. The tags are as follows:

Tag	Remarks
filename	The name of the file; you may use a path to disambiguate attachments with the same filename. The filenames shown to the user in the email will not have paths.
filedata	Optional, base64 encoded file data. When you specify the attachment’s data, base64 encoding is required, even for files that are otherwise text-based. If the file has already been uploaded for use in a different mailing, and the file data is omitted, the file from the prior mailing will be used as-is. If the file has been previously used but you specify file data, the version of the file used by FeedBlitz will be overwritten. All file uploads are subject to anti-virus scanning, and a mailing will be rejected if any attachment appears to contain malware.

The example XML therefore specifies three attachments:

• test/abc.txt
• helloworld.txt
• group.txt

Of these, only helloworld.txt has associated file data (note that it is base64 encoded); so the other two files must have been uploaded for a prior mailing.

The files will be visible in the FeedBlitz UI for the account associated with the API Key in the single mailing campaign’s asset / attachment browser.

Sending Follow-Ups: The <remail> Element

The <remail> element allows you to send an email to subscribers based on their status and optional interactions with a previously sent mailing.

Use cases include:

• Sending to everyone not on the list when the original was sent
• Sending to everyone who opened (or who didn’t open) the original mailing.
• Sending to everyone who did (or did not) click on a specific link.

<remail> XML has the following elements. Optional elements, if specified, must be specified exactly and only once.

Tag	Comments
<mailingid>	Required: The mailing ID you’re following-up on.
<lists>	Optional: Comma separated additional lists to take into account for the original specified mailing
<function>	Required: One of the following strings: sent – people sent the original email. notsent – people who are on the list now but weren’t sent the original opened – subscribers who opened the email. notopened – subscribers who were sent the email, but who apparently didn’t open it. clicked – readers who clicked a specific link in the original mailing (you must specify the link ID). sentnotclicked – anyone sent the mailing but did not click the link, regardless of whether they opened the email or not  (you must specify the link ID). allnotclicked – everyone active on the list now but who did not click the link then (you must specify the link ID).
<link>	Optional: An ID corresponding to the tracked link in the email.

DELETE – Delete a scheduled mailing

Deletes the mailing from the schedule, provided that it is not currently launching. You must specify a <scheduleid> parameter in XML, or as a URL parameter, or in the resource path, as in DELETE /newsflash/<listid>/<scheduleid>

Check the returned XML’s status for whether the deletion worked successfully (and if not, why not).

On Demand

Resource path: /ondemand/<listid>

Methods:         PUT, POST

Either PUT or POST works; they are synonyms. There is no difference in the XML sent / returned, nor in their effects.

To send an on demand mailing, POST or PUT the required XML to the list’s ondemand resource. So, for example, to send an ondemand mailing to all subscribers on list ID 84 consisting of two posts:

Resource URL:           /ondemand/84

Posted XML:

<?xml version="1.0" encoding="utf-8" ?> 
  <feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
  <ondemand>
  <link>Guid for first post</link>
  <link>Guid for second post</link>
  </ondemand>
</feedblitzapi>

The parameters you send are the same as for Newsflash, with the following changes:

• <message> and <textpart> do not apply and should not be specified
• Specify one or more <link> elements which are entity encoded GUIDs or post URLs
• The underlying RSS feed must have unique GUIDs (<id> elements in Atom) or links, to enable FeedBlitz to correctly disambiguate similar posts from the feed. If this is not possible the mailing attempt will fail with an appropriate error returned to the caller.
• The link elements must be in the current feed visible to FeedBlitz. If not, FeedBlitz will not be able to find the post content and the mailing will fail. If this happens unexpectedly and you use server-side caching ensure that FeedBlitz can defeat the cache (or that caches have been properly flushed) prior to sending an on demand mailing to reduce the risk of a <link> not being found. It may also happen in the event of server side failure or performance problems. FeedBlitz times out fetches at 20s.
• You cannot specify the same link (feed post) multiple times.
• The <link> contents will be checked against the feed item’s link and GUID elements, to enable on demand mailings for feeds using formats that don’t supply GUID or ID elements. You may therefore specify the post’s URL in the <link> as it appears in the source feed. It is recommended, however, that you provide the GUID (or <id> element if your feed is Atom) as these elements are required to be unique according to the specs.

IMPORTANT: Once a mailing starts it cannot be stopped.

With test mode enabled no activity will occur but the API will report a success in the response along with a warning that test mode is on.

The returned XML gives the mailing ID of the campaign if it launched successfully in the following form:

<ondemand>
  <mailingid>1234</mailingid>
</ondemand>

SendMail – Send a one-off email to named subscriber(s)

This resource sends a one-off email to an existing, opted-in subscriber to a list owned by the account. The list ID is required for tracking, metrics, bounce handling and providing the correct unsubscribe option. It is significantly more efficient (read: much much faster) to use this API to email a single or few known readers than to send a Newsflash or OnDemand mailing to an entire list with a email=”subscriber@example.com” segment, or the email addresses in a group.

Resource path: /sendmail/<listid>

Methods:         POST

Sample Posted XML:

<feedblitzapi version="1.0" >
    <sendmail>
        <subject>This & that - an API initiated mailing</subject>
        <message>
            <h1>Headline</h1><p>Something or other</p>
        </message>
        <fromname>Philbert</fromname>
        <fromaddress>phil@hollows.com</fromaddress>
        <testmode>0</testmode>
        <recipients>phollows@gmail.com</recipients>
    </sendmail>
</feedblitzapi>

Tag	Comment
<subject>	Required. Entity encoded subject. May contain HTML tags that will be removed from the email subject line, but will be included in the body of the email if the list’s active template uses the <$BlogDescription$> tag
<message>	Required: The HTML markup, entity encoded to be valid XML.
<recipients>	Required: Comma separated emails. Any emails not active (i.e. unsubscribed, deleted from the system, not yet activated, or simply not found) on the list will be suppressed
<fromname>	Optional: Override the list’s settings with this friendly name
<fromaddress>	Optional: Override the list’s settings with this sending address.  This is also the reply-to address.
<testmode>	Optional: If 1, the email won’t be sent. Useful for testing API interactions without aggravating real subscribers. Default value if not specified is 0 i.e. email will be sent.
<tags>	Comma separated list of entity encoded categories or tags. Will be added to the SMTP headers and email apps which display categories (e.g. MS Outlook) will show them
<usetemplate>	Optional: Disable the list’s template for this mailing, if sent to 1. In which case the HTML specified in the <message> element will be sent as is. Otherwise, the message will be treated as a virtual blog post / RSS entry and formatted with the list’s current template. Default value is 1.
<textpart>	Optional: Specify the text alternative to the main HTML message to be sent as a text MIME part in the mailing. If none is specified, FeedBlitz will automatically generate a text part from the HTML message.
<schedule>	Optional: If omitted, the mailing launches immediately. If present, the mailing will be schedules at the specified date and time, provided that the date and time is in the future. You should specify the date and time with time zone offsets, e.g March 11, 2020 at 5:04pm US Eastern Daylight Time is 2020-05-11 17:04 -0400. If you do not specify a time zone offset, FeedBlitz treats the date and time as if they are UTC. Important: – Seconds are ignored and set to 00 – The schedule you want might not be available, in which case the scheduled time will be moved to be later (and is present in the returned XML along with a warning status message)

IMPORTANT: Once a mailing starts it cannot be stopped.

With test mode enabled no activity will occur but the API will report a success in the response along with a warning that test mode is on.

The returned XML gives the mailing ID of the campaign if it launched successfully in the following form:

<sendmail>
  <mailingid>1234</mailingid>
</sendmail>

If you schedule the mailing, the returned XML parallels the /newsflash schedule XML. Further, you can then GET and DELETE this mailing via the /newsflash resource and the returned <scheduleid>

<sendmail>
  <scheduleid>1234</scheduleid>
  <schedule>2020-05-11 21:04:00 +0000</schedule>
</sendmail>

Attachments

The /sendmail resource permits attachments. See the attachments XML documentation above for information on specifying and using attachments.