Mailings

Overview

Create, target, send, and manage your emails from the Mailings Tab. Increase the effectiveness of your mailings with customization, head-to-head testing, and precise recipient targeting. Send your Mailing immediately, schedule it for later or make it recurring.

Customizations

ActionKit offers several options for customizing the appearance and content of your mailings. You can use snippets, merge files, and merge queries to insert content specific to each user, use email wrappers and custom fields to create a custom look for your mailings, and insert images or video.

You can also customize parts of your ActionKit admin interface. You can add additional fields in the Content section of your Mailing Compose screen by using mailing templates. And also create custom dashboard reports to run on the Proof and Send screen of your draft mailings and another on your sent mailing Report screen.

Testing

Testing is smart! So we made it easier with built in head-to-head testing of subject lines or full mailings.

  • Enter your subject lines, view a comparison report, then select the winner to send to everyone who didn't get the test, see Subject line testing.
  • Perform head-to-head tests of everything from full mailings to different layouts or images with A/B Test Groups.

User Targeting

Extensive options allow you to specify recipients based on location, past actions and interests, previous donations, and more. Or, use our point-and-click interface to write a query using more sophisticated criteria. See Target.

Creating Mailings

Mailing creation is accomplished with three steps:

Compose

On the Mailings tab, click Create New Draft. On the Compose screen enter the content and related settings.

Basics

Subject and Preview Text

Enter the subject line for your mailing. A compelling subject line can significantly increase your action rates.

The lower text box is for preview text. Preview text is the text that most email clients will display after the subject. In Gmail, for example, preview text is displayed after the subject with a dash between subject and preview text. Adding preview text is completely optional. If you don't add any, email clients will just pull it from the first text in your mailing's content.

For preview text to work, your email wrapper must support it.

You can easily run a test to see which of two or more subject line and preview text combinations performs better with your list and send the winner to everyone who didn't receive the test.

To run a test, just enter two or more subject lines. Click the plus sign (+) to add more subject line fields. Read more about Subject line testing. When you add another subject, the preview text from the previous subject line is copied. You can edit it or just leave it and use the same preview text for both.

As a shortcut for bulk creation of subject lines, you can also copy multiple subject lines from a document (with one subject line per line) and then paste it into a mailing subject field, which will then create additional subject fields to hold them all.

You can use copy and paste snippets to insert user-specific content in your subject line.

From

Select an email address to appear in the From Line of your Mailing. You can also click the Custom From line link to enter an email address for one-time use.

From lines should follow this format: "Tanya Africa, ActionKit.com" <tanya@actionkit.com>. The name section should be quoted.

You can also use snippets in your standard and custom from lines to generate dynamic from lines that vary depending on the recipient for mailings, event emails, and transactional emails. These could be merge snippets, custom user and action fields, or any other data that is able to be evaluated as a snippet in your from line.

The final from line at send still needs to follow the same format as from lines without snippets; from lines that do not pass validation will kill the mailing and you will receive a notification that your proof or mailing has died.

Warning

You almost always want your main ActionKit domain on every mailing's From line. ISPs' spam filters treat new and unknown domains harshly, so splitting your mail traffic between domains has deliverability risks. Changing From domains has limited branding value anyway: the From name and subject are usually shown more prominently. We suggest changing From lines' name and, if you want, the email username:

  • "Tanya Africa, ActionKit.com" <tanya@actionkit.com>
  • "Tanya Africa, My Separately Branded Campaign" <separate.campaign@actionkit.com>

But we advise against per-campaign From domains like this:

  • "Tanya Africa, My Separately Branded Campaign" <tanya@separate-campaign.com>

So, by default, if you try to change the From domain, we'll replace it with your primary domain on the From line, and use your alternate domain in a Reply-To header instead. When we do this, you'll see a note under the From line field saying so.

If, despite the risks, you definitely want to use other From domains, contact us via support. We'll need to change your instance configuration, and you'll need to do some DNS setup for the new domain.

From the Mailings Tab, click From Lines in the sidebar on the right under Content to see your existing From Lines. From this screen you can add a new from line, edit or disable (by hiding) an existing from line, or re-enable (by showing) hidden from lines.

Reply To

Enter an email address here if you want your recipients' replies to go to an email address other than the From Line for this mailing.

Notes

Notes are not displayed to recipients. They show on Mailing lists on the Mailings tab and the Browse All results screen. Use for differentiating between multiple mailings with the same subject line and for other internal purposes.

Tags

Tags are words or phrases you can associate with a mailing. The tag list is the same for pages and mailings, but unlike with pages, when you associate a tag with a mailing no users are associated with the tag, whether or not they receive the mailing.

Tags are used to categorize your mailings. Tags are displayed on the Mailings Tab and the Browse all listing, and you can filter by Tag. For example, you can quickly view the list of all the Mailings you have created for a particular campaign.You could also write a custom report analyzing mailing performance by tag.

To edit, add, or hide a tag, see Working With Tags.

Email Wrapper

Email wrappers define the header and footer appearance and content for your mailings. You can also use them to create mailing templates to customize your mailing Compose screen.

The default wrapper doesn't include any appearance settings, but it does include a link to your default unsubscribe page. You can link to a different one, but you must link to one of your unsubscribe pages.

If you do not select an email wrapper for your mailing, then the mailing will be sent with a bare wrapper that has no appearance settings and a link to your default unsubscribe page.

You can create as many wrappers as you'd like. We've also provided some built-in examples of wrappers.

Click the Email Wrappers link on the Mailings Tab, to see a list of all your current wrappers, ordered alphabetically after the default wrappers (remember you may have a default for each Language).

Read more about creating new email wrappers.

Landing Page

Certain snippets require you to select the page that defines information included in the snippet. Snippets related to an e-delivery or targets for call, whipcount, letter and petition pages all require a source page, as do donation snippets. For more information, see:

Merge Query

Merge queries work in a similar way to merge files, but instead of uploading the data to add to your mailing, you write a query to pull data from the database and the results are joined to the users targeted by your mailing. This is useful for grabbing data that exists in the database but is not automatically put into the mailing context, like extended legislator and event data, or custom action field values previously submitted by users.

The first column of the merge query is the key used to match targeted users to the query results. This can be a geographic designation (like country, state or zip), or a user source or unique identifier (user_id or email), but must only have one row per key.

The other columns in the query results are the value or values you want to insert. Once you've selected a merge query on the Compose screen, you'll see a snippet for each column name if you click Snippets then Merge Query in the Body section.

The Merge Query Snippets use the prefix "query" followed by the name of the column: {{ query.column_name }}. As an example, if you write the following merge query, the available snippets on the Compose screen are {{ query.id }} and {{ query.favorite_color }}.

SELECT ca.user_id AS id, caf.value AS favorite_color
FROM core_action ca
JOIN core_actionfield caf ON (ca.id = caf.parent_id)
WHERE ca.page_id = {{ page_id }}
AND caf.name = 'favorite_color';

You can click to insert the {{ query.favorite_color }} Snippet in the mailing, and the current recipient's value for that custom field from the specified page will be included. The Merge Query Snippets include requires_value so your mailing doesn't display a blank if a targeted recipient doesn't have a value returned by the query. That user is skipped. Read more under failed deliveries.

Alternatively, you can remove requires_value and use a conditional block ( {% if query.favorite_color %} ... {% endif %} ) or a default ( {{ query.favorite_color|default:"ultraviolet" }} ).

Merge Queries are just Query Reports with a few specific requirements:

  • They must be tagged merge.
  • They must declare a name for every column using the AS SQL alias keyword. This is true even when the natural name of the column would be the name you want, e.g. SELECT core_user.id AS id
  • The first column returned by the query must be one that can be matched to users.
  • The merge query cannot contain a UNION.

You can use any of the following fields for the column users are matched on:

  • id (core_user.id or user_id in other tables like core_action)
  • email
  • city
  • state (the 2-letter abbreviation, e.g. "FL")
  • city, state (special case where we'll match on two columns because some city names are not unique (e.g. Springfield); if city and state are the first two columns in your merge query we'll automatically use both to make sure we get the correct value for each user)
  • region
  • postal
  • zip
  • country
  • source
  • us_district
  • us_state_senate
  • us_state_district
  • us_county, state (same behavior as city, state)
  • loc_code
  • country_code
  • region_code

(You can also match on prefix, first_name, middle_name, last_name, suffix, address1, address2 although they seem much less useful!)

If you want to write your query using the query builder, be sure to click the As button for each of your display fields, so that you can specify column names.

Once you've created a merge query, it will be listed in the dropdown for Merge Query on the Compose screen. Add a new one by clicking on the plus sign next to the dropdown. If you write a Merge Query with parameters, you will be able to enter values for the parameters when you select it on the Compose screen. In addition, any help text you write for parameters will be displayed above them when the Merge Query is selected. You can reuse a Merge Query on multiple mailings with different parameter values.

If you have a particularly slow merge query and you want to cache the results, you can use the Refresh setting on the query report just like you can for targeting queries. If you don't cache the results, they will be refreshed when the mailing is sent, or when the mailing set is rebuilt if you select the option on the Target screen to use the merge query for targeting.

Merge File

Use Merge Files to insert user-specific information in your mailing from a CSV or TSV that you upload. For example, you may want to use highly localized goals based on users' cities: "We need 5 more volunteers in Oklahoma City today!", or to show users the best paper for an LTE based on their zip code.

The first column of the merge file is the key used to match targeted users to a row in the file. This is usually a geographic designation (like country, state or zip), but you can also match on the user source or unique identifier (user_id or email).

The other columns are the value or values you want to insert. Once you've selected a merge file on the Compose screen, you'll see a snippet for each column header if you click Snippets then Merge File in the Body section.

The Merge File Snippets use the prefix "merge" followed by the name of the column: {{ merge.column-name }}. As an example, if you uploaded the following merge file, the available snippets on the Compose screen are {{ merge.zip }} and {{ merge.paper }}.

If you upload a file with the columns "zip" and "paper":

zip, paper
10014, New York Post
19130, Philadelphia Inquirer
94965, Marin County Chronicle
60632, Chicago Tribune

You can click to insert the {{ merge.paper }} Snippet in the mailing, and the paper that matches the user's zip code will be included. The Merge File Snippets include requires_value so your mailing doesn't display a blank if a targeted recipient's zip code isn't in the file. That user is skipped. Read more under failed deliveries.

Alternatively, you can remove requires_value and use a conditional block ( {% if merge.paper %} ... {% endif %} ) or a default ( {{ merge.paper|default:"your local paper" }} ).

See Managing Merge Files for the full list of options for the first column and for details on creating and updating merge files.

Note that merge files will be deleted 30 days after last use. This applies to merge files that were last used in a mailing that was sent 30 days ago, or in a draft that was last updated 30 days ago. If a merge file is not connected to a mailing it will be deleted 30 days after upload.

Merge files require Amazon S3 to be configured.

Content

The elements that show in this section are defined by your email wrapper. Every mailing should have a Body section.

Body

The content of your mailing is entered here.

WYSIWYG

Most everywhere that you can enter and edit text (e.g. page content text boxes, mailing body), we've provided a basic WYSIWYG editor (TinyMCE) and a syntax coloring editor (CodeMirror) as well as the standard browser text area.

  • Select Visual to use the WYSIWYG editor and view the rendered content without writing your own HTML. The toolbar has buttons you can use for standard functions and formatting. Just hover over the tool to see the name. For example, you can click to indent a paragraph or to insert an image. The show/hide toolbars button opens a second bar with additional formatting options.
  • Select Code in the toolbar to have color-coding and line numbers for easier editing of the code. Different elements, like Javascript or CSS, are given different tinted backgrounds or text colors.
  • Select Plain to remove all highlighting.

Note

The visual editor, like other WYSIWYG editors, may at times add more than you expect to the HTML, like extra <p> tags, and at other times, strip out things, like styling. You may want to avoid the visual editor when updating code-heavy items such as mailing wrappers and templatesets, and limit the use of the visual editor to areas that are more content-heavy, like page text and mailing body content.

Spell Check

We've made it possible for you to enable your browser's native spell checking when using the WYSIWYG visual editor, at least for most major browsers. The keyboard shortcut, menubar command, or context menu option required to enable spell checking is different in each browser, but typically you can right-click (or control-click, or two-finger-click) on an editor panel to reveal the 'Spelling' or 'Spelling and Grammar' commands for it. Firefox users may have to begin by selecting 'Install Dictionary' to enable spellchecking the first time, if they have not already done so. This enables 'check spelling as you type' functionality in Mac Safari, Chrome and Firefox as well as possibly Windows for Chrome, Firefox and IE 10+.

Snippets

Snippets are click-to-insert template tags used to display information specific to each user within the text on your Pages and in Mailings.

For example, if you wish to identify the user by name, you would expand the User header under Snippets and select First name. The following Snippet of code will be inserted into your HTML:

{{ user.first_name|default:"Friend" }}

On the backend, composing and targeting your mailing are separate. It's particularly important to keep this in mind when using snippets. There are some safeguards built in to help you avoid sending a mailing to a particular user with a blank value for a snippet:

  • Default: Users who don't have a value for the field will see the default value defined for the specific Snippet. For example, if you insert First name, a user will see the default, 'Friend', if the first name field is blank in their user record.

    You can change the default value by typing over it when you insert it, but not universally for the Snippet.

  • Requires value: Some snippets don't have a default and should only be used if the user has a value for the snippet. For example, the "highest previous" snippet only works for donors.

If your targeting includes users who have never donated, ActionKit will skip them, rather than showing a blank for the Snippet. You can see information about any users who are skipped in the Mailing report.

It's better to select the right targets (in this case, for example, by limiting to donors) than to rely on this safeguard because building the failed mailing list adds to your total send time.

You can delete "requires value" if you want to send the Mailing to users whether or not they have a value for the field. In these cases you may want to add a Default. For example, you could change the snippet below for Sen./Rep. Smith:

{% requires_value targets.title_last %}{{ targets.title_last }}

to:

{{ targets.title_last|default:"Your Senator" }}

if you are linking to a page that targets Senators.

In any case, if you customize your snippets we suggest viewing a larger sample of proofs to help avoid nasty surprises.

Some Snippets can only be used if ActionKit knows what page to use to determine the value. Select the appropriate page in the Landing Page dropdown.

As an example, the Snippet for Suggested Ask requires that you select a donation page, which will be used to look up the Suggested Ask formula.

The dropdown is not a complete list of all your pages. Only those with information that might be needed for a mailing are displayed (e.g. no signup pages are included).

View the snippets and the code they insert for Mailings.

Preview

You can view your rendered HTML as it will appear for a randomly selected end-user in the Preview section. If you want to see the preview as it will appear for a specific user, enter the user id. The preview should update in real time as you make changes but if it appears to be behind, click 'Update Preview'.

Advanced Options

Plain Text

ActionKit will automatically generate a text version of your email. Both versions are sent to each user; the user's email client displays the text version if HTML is unavailable. If you prefer you can provide your own text version here by clicking Edit Plain Text Version.

Web Viewable

Your mailing can include links to "view this mailing as a web page". To enable this:

When combined with the AKID that is added in the mailing process, this link will re-create the email message for the specific user. For example, http://docs.actionkit.com/mailings/view/123?akid=123.5678.UB-drT generates a view of Mailing 123 for user 5678.

If the AKID doesn't include an authentic hash generated by ActionKit (e.g., if the user wasn't sent the mailing), we'll display an anonymized version using the city, state and postal code for the first recipient of the Mailing. No other user data, like name, is displayed. This prevents third parties from arbitrarily requesting a view of any user's mailing.

You can use the anonymized version yourself with a link to http://docs.actionkit.com/mailings/view/123.

Some mailings cannot be viewed anonymously, because they include {% require_value ... %} tags which look for values an anonymous user lacks. For example, donation snippets which require recent donations will always fail for the anonymous user because it hasn't placed any orders.

Note

Anonymous web views of your mailing are recorded in the core_open table with user_id 0.

If you want to enable web viewing but be sure that a Mailing isn't visible without a matching AKID link, you can add {% require_value user.id %} in your Mailing; all real users have an ID, so this will only fail for anonymous viewers. If any require_value test fails, we display the message "we couldn't generate a view of this mailing."

Mailing views are formatted to look like the contents of the message in an email client. The message uses the Email Wrapper, not a Page templateset wrapper.

Mailing views are re-created based on the current information from the database, and therefore may not precisely match the version of the Mailing that was actually emailed to a user. For example, if a user moves to another state after a Mailing is sent, and then clicks the view-as-web-page link, they will see a new version of the Mailing that might include different legislative targets for their new address. Similarly, if you change the Email Wrapper after sending a Mailing, users who later click the view-as-web-page link will see the new wrapper rather than the version that was sent to them.

If a web-viewable mailing used a mergequery for targeting, we save data from mergequeries that aren’t cached for one week. During that week, web views are available. After that the user will not be able to view the mailer, and instead will get a generic mailing view error message.

Note

This option is not available for signature deliveries to legislative targets.

Is Model

Model mailings are drafts that you've designated as templates to be copied as the basis for other mailings. Model mailings can not be sent.

You may want to create different models for particular kinds of mailings to save time and help enforce business rules. For example, if you have a C3 and a C4, you might have a model fundraising appeal for each where you've selected the proper from line and wrapper and limited the targeting to the correct list. Later, you can copy the appropriate model to create a a draft that shares those common elements, edit it as needed, and send it normally.

To designate a mailing as a model simply click the Is Model checkbox.

Note

Only staff users with the Mailings - Edit plus Model Mailings permission and superusers can create and edit model mailings. The checkbox to designate a mailing as a model will not show up for other users.

Custom Mailing Fields

As with custom page fields, you can use these fields to insert a section of content or code in your Mailing or Email wrapper, or to create a mailing template.

After you've created the custom Mailing Field, add the field to the body of your Mailing using this syntax: {{ custom_fields.FIELD_NAME }}. Or, if your custom Mailing Field contains template tags or filters that need to be interpreted, then use this syntax instead: {% include_tmpl custom_fields.FIELD_NAME %}.

Then in the custom field row toward the bottom of the screen, select the field name on the left and enter the value on the right.

Read more about creating custom mailing fields here.

Send Proofs

Then use the buttons at the bottom to continue on to recipient selection or to generate one or more proofs (see Send Proofs).

Target

Includes and Excludes

Make selections in this section to build your target set. Only subscribed users will be emailed.

Target Sets

ActionKit finds all the users that match your selections and who are subscribed to one of your mailing lists, then saves that set of users. Building your target set when you save your mailing makes complicated targeting and proof generation faster.

If you change the criteria, ActionKit will rebuild the set. Or, you can force a rebuild of the mailing set at any time from the Proof and Send screen.

After 30 days, target sets that have been saved to your database will be deleted unless the Mailing was stopped or died. The ID of every user who was sent a Mailing is saved to the core_usermailing table which is never deleted so you won't lose mail history.

Logic

Below we describe the logic used to combine your choices and describe the categories available.

Your selections within and between categories are joined as follows:

Criteria within a given category (e.g. "States" or "Mailings") are combined using "OR." "OR" makes your target set larger.

Example: If you enter "NY, RI" under States your set is everyone in both states. This is the same for actions, lists, etc.

(The rules for the Custom User Field and Custom Action Field categories are a little bit more complex. See the full explanation on those below.)

Categories under Includes are combined using "AND". "AND" makes your target set smaller.

Example: If you enter "NY" under the "States" category, then click Add Criteria To This Set and select "Has Donated" under the "Donors" category your target set will include only people from NY who have donated.

All your selections in one green section (which may include multiple categories like States and Donors in the example above) are part of one inclusion set.

You can create additional inclusion sets and join them using "OR" by selecting Also Include Another Set Of Users.

Example: Continuing with our example, where you're targeting NY donors, if you click to "Also Include Another Set of Users", select "Add Criteria" and enter "CA" under "States", your set will target NY donors as well as everyone in CA.

Alternatively, if you select "NY" under "States", include another set and select "Has Donated" your target set will include anyone who has donated, regardless of where they live, and anyone who lives in NY, regardless of whether they've donated.

Categories under Excludes are combined using "OR". So if you exclude donors and NY, you won't have any of either in the result set.

Raw SQL is handled by building a temporary table of people matching the criteria and then using "AND" (for include) or "OR" (for exclude) to combine it with other criteria.

Special criteria are joined to the set of users defined by the includes and excludes using "AND". So, if you're targeting donors from NY and you check the box to target constituents of your landing page's advocacy targets, only donors in NY who live in the relevant districts will be included in your target group.

Selections

Click on either Add Criteria or Exclude Groups to see the options described below. Many of the categories have built in tool tips that will display when you hover over the field's label.

Actions

  • Actions - Start typing the page id, name, title or tag to find all users who successfully completed an action on the matching page. Failed actions (like rejected donations) don't count. The dropdown includes the last 250 pages, plus any page that's been used in Mailing targeting in the last 14 days.
  • Custom Action Fields - You can select uers based on their custom action fields. Click in the box to select a custom action field, and optionally a page and specific values to match.
    • If you don't choose a page, you can choose custom action fields from any page to match. If you do choose a page, the list of fields will update to reflect the fields in actions from that page.
    • You can enter a single value to match or multiple values separated by commas, semi-colons, or returns. If you enter multiple values, they will be combined using "OR", e.g. a value of "cat, dog, ferret" would match users with any of those values in the selected field. Entering no value at all will match all users who have the field, regardless of the value they have in it. If you add multiple fields, they will be combined with "AND".
  • Donors - Selecting donors displays two options:
    • Has Donated - Any user who ever donated either through an ActionKit donation page or according to imported user data. The user's total donations must be more than $0 (i.e., a user who has only ordered a free product will not be included).
    • Monthly Donors - This box provides several selections to help you manage recurring donors, including: any user who was ever a monthly donor, only those with a current recurring commitment, those whose cards have recently or will soon expire, or those who canceled in the last week.
  • Event Campaigns - Selecting event campaigns displays the following targeting options:
    • Near Event Campaigns and Campaign Radius - These two must be used together with each other, and with a snippet described in the guide to attendee recruitment for events.
    • Same State Only - Limits users who are within the campaign radius to only those in the same state. Useful if events target state officials like governors or U.S. Senators. Use the special user.state as state variation of the snippet described in Attendee Recruitment Emails.
    • Same District Only - Limits users who are within the campaign radius to only those in the same U.S. Congressional district. Useful for events that target U.S. Representatives. Use the special user.location.us_district as us_district variation of the snippet described in Attendee Recruitment Emails.
    • Date Range - Optionally specify a starting and/or ending date to be used when searching for events. You may use a specific date, such as "2020-11-03", or a number of days from the present, such as "7" to represent one week. Leave these fields empty to match all events.
    • Event Fields - Optionally filter events based on custom fields saved when the event was created. To match any one of several values, separate them with a comma, semicolon, or line break. If you enter multiple values, they will be combined using "OR", e.g. a value of "march, rally, phonebank" would match events with any of those values in the selected field. If you add multiple fields, they will be combined with "AND".
  • Languages - Any user with the language you specify here in their core_user record will be selected. Read more about using languages.
  • Lists - If you want to limit to users on a particular mailing list, select your list here.

Note

Unless you select a list, ActionKit will assume that your criteria apply to all users on any list. ActionKit displays a warning if no list is selected here; you can ignore it if you intend to target all mailable members regardless of list.

  • Mailings - Selecting mailings displays two targeting options:
    • Mailings - Select users based on whether they are on the recipient list for a sent mailing or a draft. You cannot use a draft that was last updated more than 60 days ago for targeting. The mailings box includes a dropdown that displays the last 60 days of sent mailings. Start typing the subject, id or tag to select mailings sent more than 60 days ago.
    • Mirror Sent Mailings' Excludes - Ensure that if a sent Mailing excluded your draft, your draft will also exclude the sent Mailing. That's a best practice for avoiding Mailing overlap, and usually, you should leave the box checked. You can see which mailings have been excluded in the Excludes section of the Proof and Send screen. If there's a special situation where you want to double-hit those mailings' targets, uncheck the box. Excludes are only added when you edit your query or rebuild your Mailing set; it's normal if mailings don't show up in your targeting as soon as they're sent.
  • Tags - Any user who completed an action on a page with the selected tag, see Tags.

Location

  • City/Postcode Radius - Selecting city/postcode radius exposes two targeting options:
    • Points - Use any 5-digit zip code or a postal code followed by the country name. You can also enter a city name (followed by the country if it's not a US city) if you also enter a point radius in the following box. ActionKit targets from a point in the middle of the city and needs to know how far out you want to go from that point.
    • Point Radius - The radius finds all users w/in x miles or kilometers of the point or points entered in the points box. (You set X by selecting the mileage from the dropdown). Users who are in a zip that's on the edge of the zip radius are included whether or not their address is within the radius (some zips will have addresses within and beyond the radius).
  • Congressional Districts - Use the format CA_04 for California federal house district 4.
  • Countries - Any user with the designated country name in their user record.
  • State House/Senate - Selecting state house/senate displays two targeting options:
    • State Senate Districts - Use the format CA_004 for California state senate district 4.
    • State House Districts - Use the format CA_004 for California state house district 4.
  • States or Regions - For states, use two-letter state abbreviations. State and region are mutually exclusive, so if you want to target by region instead click the link below the box and enter the region. Regions are targeted based on the user's core_location row and NOT the value in core_user.region. Accepted syntax is: "England, United Kingdom; Scotland, United Kingdom". You can also use 2-letter country codes "Ontario, CA; Quebec, CA" . GB, not UK is the country code for the United Kingdom.
  • Target Groups - Constituents of the selected legislative target group. Define new legislative target groups from the Pages Tab.
  • U.S. Counties - Any user who lives in the designated county or counties based on their zip code. Separate counties using semi-colons, new lines, or commas. Or use the format county, state (ex: "Springfield, VA") if there are counties with the same name in multiple states.

Custom

  • Query Library - Click in the box to select a query from your library. Select the query from the drop down list and click Add Query. To add a query to the library, click Write a new query. To edit an existing query, go to the reports tab and search for the report by name. For more information, see Query library reports.
  • Raw Queries - Enter a SQL statement for targeting that you can't perform with options above. Your select statement must return the user_id and only the user_id. The mailer will automatically exclude any users who aren't subscribed, so you don't need to include this in your query. You can include more than one query by separating them with a semi-colon. For more information, see Creating a query report .
  • Users - You can include or exclude individual users by User ID. You can find an individual's User ID by searching for them on the Users Tab, see About end user accounts.
  • Custom User Fields - You can select users based on their custom user fields. Click in the box to select a custom user field, and optionally enter values to match. You can enter a single value or multiple values separated by commas, semi-colons, or returns. If you enter multiple values, they will be combined using "OR", e.g. a value of "cat, dog, ferret" would match users with any of those values in the selected field. Entering no value at all will match all users who have the field, regardless of the value they have in it. If you add multiple fields, they will be combined with "AND".

Auto Excludes

If you've enabled auto excludes, you'll see a checkbox below the Add and Exclude sections. Check the box to include this mailing in your priority ordering for mailings to be sent on the day you select.

Limits and Ordering

Limit - Used for testing. Enter a number here to limit the number of users to receive this Mailing. Select a number that's lower than number of users who match your targeting selections.

For example, if you have 100,000 users in California but you only want to send this email to 10,000 of them, enter CA under State and enter 10,000 in the limit box. Read more about testing at testing your mailings.

If you set a limit, random will be pre-selected by default under Order by.

  • User ID - By default ActionKit will send to users in order by ID, lowest to highest.
  • Zip (east-to-west): Zip sends to users in order by zip from east to west.
  • Shuffle randomly: Sends in random order. Generally used in combination with limit above to send an email to a random sample of targeted recipients for testing your mailings.

If you don't include a sort order, ActionKit will automatically order the names by id, which generally means oldest to newest.

Max emails/sec - Usually you'll want us to send your emails as fast as we can and you won't use this option. However, there may be times when you'd like the emails to trickle out. In that case, you'd enter a number here. The low end is 2 mails/second and the high end is 300/second.

The classic use for this feature is to send call alerts slowly enough to avoid lots of your users getting a busy signal. It may also be useful if you are sending users to a partner with limited network or server resources.

Note

If your mailing is a timed send (sending to users in their local time zone or using a merge query/merge file), the Max emails/sec feature cannot be used and will be unset.

Automatic Subject Line Testing

If you've given your mailing multiple subject lines, you will see the option to use automatic subject line testing. If you click the box next to "Send the winning subject line from this mailing to the full targeting with the limit removed" you will be presented with some controls for the automatic testing.

  • Wait Time - This controls how long ActionKit will wait for results after the test is sent. When the time is up, the winning subject will be chosen and sent. The best way to determine how long to wait is to look at your past mailings to see how long it takes for a significant number of people to react to them.
  • Metric - What should be used to determine the winner of the subject line test? Your choices include opens, clicks, actions, and the amount of money raised for each subject.
  • Max Unsubscribe Rate - Some groups like to check the unsubscribe rate on their test mailings before sending them to a wider audience, just to make sure they didn't accidentally send something off-putting that might be making people leave the list. You can automate this by setting a maximum unsubscribe rate here. If the unsubscribe rate on the test mailing goes higher than this, the larger audience resend will be canceled. You can enter decimal numbers here, e.g. 0.1. The best way to determine normal unsubscribe rates is to look at your past mailings.

Note that you must set a limit to use the testing feature. The test mailing will go to the number of people you limited to, and then the winner will be resent with winning subject and no limit, excluding people who have already received the test.

Automated subject line testing can't be combined with A/B testing, so this option will go away if you add the mailing to an A/B test group.

Note

If you are using auto excludes and try to add a mailing with automatic subject line testing to the exclude order, it can give unexpected results. The problem is that the mailings that exclude the automated subject test mailing will only exclude the users for the test, not for the full send that follows. If the other mailings for the day have already sent by the time the subject line test finishes, there may not be any audience left to send the winning subject to. You can prevent this from happening by waiting until the subject test has sent the winner before sending the other mailings.

A/B Testing

Check the box to make this mailing part of a test group. Pick an existing test group or create a new one.

Test groups allow you to group two or more mailings to make head-to-head testing easier and more foolproof. Using a group helps protect against common testing mistakes by making sure the mailings' targeting criteria and rough size match, that the groups don't overlap, and that they're launched at the same time. They also help simplify the process by letting you review and launch the whole set of mailings from one screen, and use a few clicks to compare the mailings with statistical details and launch the winning mailing.

You can still run manual tests, using the Compare Mailings report to compare performance. In some cases this is the better approach. Test groups only make sense when mailings' targeting, size, and launch time all match: they're not designed for testing three petitions to three different list segments, or testing sending the same message on different days of the week. Groups also aren't available for petition delivery mailings or recurring mailings. And for small variations in message content, it may be simpler to create your own test using the mod filter.

Read about creating and working with Test Groups.

Proof And Send

From this page you can:

Preview Your Mailing

Click Preview next to the Content header in the Compose section to see the Mailing and wrapper as it will appear to users. This can take up to 30 seconds to load. While it's loading, the area will be blank. Click Close Preview to switch back to viewing the Content table.

If you have conditional content in your Mailing, like user.first_name, ActionKit will display the name of a recipient based on the targeting selections you've made with two exceptions.

  • Since this is just for preview purposes, ActionKit may display a user who is unsubscribed and who will not be sent the final Mailing.
  • A test user (named 'test') will be displayed if a count has not been generated for your Mailing, see Force a rebuild of the Mailing set.

Review Targeting Data

The Targeting table contains the number of recipients, the limit, and sorting criteria based on your target selections on the Target screen. You can view the SQL generated by clicking View SQL. This can be a helpful resource for learning more SQL and more about the ActionKit data structure. You can also go back to the Select Recipient screen by clicking Edit.

Force Mailing Set Rebuild

The users matching your targeting criteria are saved as a target set. You can rebuild the set any time using this link.

Even if you haven't changed the criteria, it's a good idea to generate a new count by clicking force a rebuild of this mailing set unless you just created the Mailing. Otherwise you may miss users who didn't meet the criteria previously. For example, if you're targeting signers of a particular petition you have to rebuild the mailing set to include anyone who signed since your last rebuild.

You can see an estimate of the build time (based solely on the last rebuild) on the Target screen while it's building.

Once you forced a rebuild, click the reload link at the bottom of the page to refresh the load information. The mailing set information will be refreshed and you will be sent an email with the new recipient count.

Draft Dashboard

If you have defined a Draft Mailing Dashboard Report it will appear here.

Send or Schedule Your Mailing

You can:

  • send now, by clicking Send,
  • schedule by selecting schedule for later, or
  • set the Mailing to send on a regular basis by selecting make recurring. Read about settings for Recurring mailings.

When you click the red button to Send (or Schedule or Start recurring Mailing), you will be asked to confirm that you really want to send (or schedule) the Mailing.

When your Mailing is sent, any staff user with the permission "Receive All Mailings" will be sent a copy of the final version with a subject beginning "[Final Mailing." Read more about staff permissions.

Scheduling a Mailing

To set a later send time for a Mailing, select the Schedule to send later checkbox and enter the Date and time for the delivery.

The time zone will be displayed after the delivery time. If this is not your desired time zone, click the Change Time Zone link in the page footer, select the proper zone from the dropdown list, and click Save.

You can cancel the send for an unsent Mailing by clicking Cancel in the Actions column of the Scheduled Mailings listing on the Mailing Tab, see Mailings dashboard.

Click Rebuild at send to force a rebuild of the Mailing set immediately before send. If your Mailing set is complicated and previously took a long time to build you may want to schedule your send earlier.

Note

When using timed sends, your targeting set only rebuilds when the targeting changes or a rebuild is requested by a staff member.

Timed Sends (BETA)
Description

Timed sends allow you specify when each recipient of a mailing should receive it. For example, you might wish to deliver a single mailing to one group of users in the morning, and another group in the afternoon.

Usage

To schedule a mailing for each user's local time click "Schedule for Later" and then check "Send to each targeted user at the time selected in their local time zone."

Send times are handled as follows:

  • missing: error
  • unparseable: error
  • more than 14 days in the future: error
  • in the past: OK, send immediately

Note

For other timed send implementations, on the Compose screen you can choose a :ref:Merge Query or :ref:Merge File with a column named send_time in addition to a key column (and any other content you might wish to merge). The send_time column must contain valid datetimes, in a format parseable by MySQL, such as "2018-07-04 12:00:00". Datetimes are interpreted as UTC.

Validation

After getting a count for your mailing, ActionKit will validate the send time for each targeted recipient of the mailing using the rules above. The "Send" button on the "Proof and Send" screen will be disabled until validation succesfully completes.

When validation completes, you may View Details to see counts for each sending interval.

If there is an error during validation, details of the error will be shown, along with a link to Retry validation once the issue has been corrected. If applicable, sample error users will be shown, along with the specific error encountered by each.

Sending

Once a timed send mailing is validated, it can be sent as usual. ActionKit will deliver timed sends no earlier than the send_time specified, but actual receipt of the email may be ten minutes or more after the that time, depending on the time itself, other mailing traffic, and delivery delays by mail service providers.

Although validation should catch errors before sending in most cases, any errors encountered during sending will be reported as Failed User Mailings.

During the duration of a timed send, a mailing will be in the "sending" status, resolving to "completed" after the last email is sent.

Cancellation

As with other mailings, timed sends can be cancelled while sending. Recipients with a future send_time will not receive the mailing.

Limitations
  • send_time cannot be more than 14 days in the future
  • No validation for timed sends sent via the API
  • Timed sends are not considered for auto-excludes. If you are concerned about double-hits, you'll need to exclude timed sends manually.

Reports & Data Capture

Individual Mailing Report

The individual mailing report is available for sent mailings only.

From the report you can:

  • Complete a subject line test, see Subject line testing.
  • View detailed stats and view the SQL used to generate the statistics.
  • View details about any mailing failures.
  • Change tags or notes associated with the mailing, even though it's been sent already, by clicking Edit to the right of the field name.
  • Send copies of the mailing to staff users.
  • Copy the mailing. A new draft will be created.
  • View the mailing's source HTML and a sample of the final sent HTML for a random user.
  • View the mailing's targeting.
  • See how fast the mailing was sent.

To view the report, click on the subject in the Mailing dashboard Sent Emails section or a mailing in the Browse All listing with a Sent status to view the mailing report.

The tables on this screen provide analytics in several categories.

Note

If you aren't seeing the results you expected, review your HTML to confirm that the links in your mailing were set up correctly. You may have disabled some tracking, if, for example, your email links to an ActionKit page that is hosted on another site but you haven't registered the domain. If you haven't added the domain, ActionKit won't track any actions back to this mailing_id. Clicks may still be attributed to this mailing (because the links go through a redirector and we identify users who arrived at the redirect by their AKID, which is then dropped when they're directed to the final URL).

If Subject Unknown is displayed, some actions initiated from this mailing can't be attributed to a specific subject. For example, If a user forwards their email to a friend, who then takes an action or makes a donation using a different email address, we're able to track which mailing yielded that action or donation, but the association with the subject line sent to the initial user is lost.

Click on any underlined name, like Forward Factor to see the definition of the word or phrase.

Links to additional mailing reports that may be useful if you encounter a problem or want to see when a mailing set was last rebuilt are displayed at the bottom of the screen for staff users with superuser permission only. The first link is to see what happened if a send failed, and the other is a history of set rebuilds.

Opens, Clicks, and Actions

The Opens, clicks, and actions table contains the following information:

Column Name Description
Subject The subject line for this mailing. If you have multiple subject lines, each will be displayed in a separate row.
Sent This is the number of mailings that were sent by subject line. Only one is sent to any given user (remember a user is an email address in ActionKit).
Unique Opens This is the number and percentage of unique opens and the number of total opens. Unique opens shows the number of users (and percentage this represents of the number sent) who we know opened the mailing. Total opens shows the number of times the mailing was opened. Because of the way opens are tracked, we don't know about every open. A tracking pixel is embedded in the body of the email message. If images display is off (which it is by default in some programs and based on your reputation in others), the tracking pixel won't register, even if the user clicks a link. Open rates are still useful for comparing performance across emails and over time. But be alert to the possibility of strange results, like more clicks than opens.
Total Opens The number of time the mailing was opened.
% Clicks Shows the number of unique users who clicked any link in the mailing, except the unsubscribe link, and the percentage this represents of the sent count.
Actions The number of completed actions.
Dollars Raised The total dollars raised if the mailing links to a donation page.
Forward Factor Shows a ratio of unique opens to total opens. This gives you a rough sense of which emails have the best record of being forwarded and then clicked. It's not a precise measure but you can use it to compare performance across mailings.

Unsubscribes and Bounces

This table shows the number of users who are no longer mailable as a result of this mailing. The user may have unsubscribed, bounced, or marked your mailing as spam.

  • Subject - The subject line for this mailing. If you have multiple subject lines, each will be displayed in a separate row.
  • Sent - This is the number of mailings that were sent by subject line. Only one is sent to any given user (remember a user is an email address in ActionKit).
  • Unsubscribes - This displays the number of users who clicked the unsubscribe link at the bottom of an email and then submitted the form to be taken off the list. The core_user subscription status for a user who unsubscribes is changed to "unsubscribed" and a row is added to core_subscriptionhistory with a change_id of 4.
  • Complaints - This displays the number of users who marked your email as spam. Many ISPs provide a list of these users and require that you remove them to maintain good deliverability. The core_user subscription status for a user who unsubscribes is changed to "unsubscribed" and a row is added to core_subscriptionhistory with a change_id of 6.
  • Bounces - This displays the number of users who had a "hard" bounce in response to this mailing. Bounced users are unsubscribed. A hard bounce is one where the email provider sent us back a code saying the address is invalid or does not exist. This count does not include transient or "soft" bounces (like a vacation auto-response) because these either resolve themselves or turn into permanent failures. The core_user subscription status for a user who bounces is changed to "unsubscribed" and a row is added to core_subscriptionhistory with a change_id of 3.
  • Total Unsubscribes - The total number of users unsubscribed as a result of this mailing. This number maybe slightly higher than the sum of complaints, unsubscribes, and bounces due to administrator unsubscribes.

Failed Delivery

Failed delivery information will only be displayed if your mailing included snippets with a required value but some of your recipients did not have a defined value. For more information on default values, see Snippets.

ActionKit skips any users who would otherwise see a blank where you've inserted a snippet and designates these skipped users as failed mailings. For theses mailing you can view the user information, view the reason for the failure, and target the failed users for a new mailing.

The following failure information is displayed:

  • View Failed User Information - The list of all failed users is shown. You can click on any user to access the Change User page on the Users Tab.
  • View Failure Cause - A partial list of the failure type is displayed on the page. For a complete list, click on the View failed listings link.
  • If you want to delete the snippet and send a new mailing to the failed users, click the Target these users in a new mailing link.

Mailing Dashboard

If you have defined a Sent Mailing Dashboard Report it will appear here.

Performance By Mailing Report

The Compare Mailings report allows you to quickly compare results from two or more mailings. Use this for mailing testing or to view recent performance or performance by tag.

To compare mailings:

1 Click Compare Mailing in the Reports tab tools menu.

2 Select the mailings you want to compare. Recent mailings can be selected from a dropdown in the top box. To include an older mailing, type a word from the subject or the mailing ID in the second box.

The dropdown includes mailings that stopped or died. These mailings sometimes have sent to a set of people before they died or were stopped so it can still be useful to see the results in a comparison.

3 Hit Compare.

You'll see various measures of performance for each mailing. In addition to the open, click and action stats available in the individual mailing report, you'll see the average gift size and the mailing sent date, plus unsub and bounce stats.

Scroll down to see information on the statistical significance of your test results. There's a table and definitions of terms to help you determine whether the performance difference between two or more mailings is statistically significant.

Mailings Data

Every time you create a mailing, a row is added to the core_mailing table. This table includes most of the important information about a mailing, including much of the information you entered when creating the mailing like the body, the from line, notes, and the wrapper id. The mailing's status is also recorded here and updated as it changes. Available status settings are: draft, queued (in line to send), sending, completed, stopped, died, and recurring.

The mailing subject(s) are in a different table - core_mailingsubject - which includes the ID of the mailing for each subject in the table.

When a mailing is sent, a row is added to core_usermailing for each user it is sent to. The subject_id field in this table can be used to join to core_mailingsubject to get the text of the subject each user received.

When a user opens or clicks a mailing, a row is added to the core_open or core_click table with the user_id and the mailing_id.

Recurring Mailings

Recurring mailings send mailings (with the same content) on a schedule, often daily, weekly, or monthly.

In ActionKit, you'll use them to:

  • Send mail when something is coming up, like if the credit card for a user's recurring donation is about to expire or an event they've signed up for is happening soon
  • Send mail after something happens, like if a user joined the list in the past week
  • Send other automated, always-identical messages, like weekly surveys to random users

Recurring Mailings in ActionKit replace 'triggers' in other systems. So, instead of setting up a trigger to email new subscribers 14 days after they sign up, in ActionKit you'd set up a Recurring Mailing targeted to people who signed up 14 days ago. You have to shift your thinking slightly to use recurring mailings if you're used to triggers, but you can generally do the same things with both.

There is one important limit to Recurring Mailings: each Mailing uses the same HTML for every send. So, you can't use a Recurring Mailing for a newsletter, or any other email that's regularly scheduled but has content specially written for each time it's sent.

Creating

Creating and writing content for a recurring draft is just like for a normal draft; the differences are mostly in targeting, sending, and maintaining the mailings once they're launched.

Read our Welcome Series FAQ for an example of one use for a Recurring Mailing.

Targeting

When targeting your Mailing, be aware:

You should almost always prevent repeat sends using the built-in query from the library.

To do that, scroll down to Query library on the Excludes side of the targeting screen, then type 'recurring' to get our built-in query for excluding People who recently received a Recurring Mailing. If you want to exclude everyone who received any recurring Mailing in the last 24 hours, enter 1 for days and 0 for all recurring mailings. You can also enter the ID for a specific Mailing or a semicolon-separated list of them.

For some likely use cases, there are built-in queries we've added to your library:

  • Recurring donation queries - Use Donors whose cards expire next Month and Donors whose cards recently failed to target recurring donors whose credit cards are either about to expire or recently failed, to ask them to sign up again.
  • Welcome series queries - Use New-to-list users to find users who joined the list exactly n days ago.
  • Upcoming events - Use Hosts of upcoming events or Attendees of upcoming events to find hosts or attendees of scheduled events. (You can't yet use recurring mailings to target those near open upcoming events, because that involves more complicated targeting that we can't do with SQL alone.)
  • List slices for "random" weekly mailings - Use Weekly slice of list to mail a fraction of users each time, e.g., 1/52nd of your list every week, for something like a tracking survey that slowly goes out to everyone.

Warning

If you use library queries for targeting in a recurring mailing, be sure that you have them set to run every time. With caching, there can be slight variations in when the report runs. So if you cache the reports, depending on when the report runs and when the mailing gets sent, you may end up targeting the same users as the previous day, or missing users that should have been targeted.

You can write raw SQL to target your mailing using MySQL date functions like now() or curdate().

For example, this SQL targets action takers from seven days ago:

select id from core_action where created_at between curdate()-interval 7 day and curdate()-interval 6 day;

Proofs

When you request counts, send proofs or use Preview the mailing, you'll get whoever would receive the message if it were sent today (or, if no one would be targeted today, you'll get an in-browser preview generated with test user data and no emailed proofs).

If that won't do, you can temporarily change your targeting so that some users are found, but of course double-check that you have re-set it to what you really want before launching the message.

Set Schedule and Confirm

Once you're satisfied your mailing is ready, go to the final screen and click the small make recurring link underneath the Send button.

Unless you want to replace a mailing on an existing schedule, click New Schedule to the right of the dropdown to open a popup. Enter a name, a time zone. You can uncheck the Notify Me When Mailings Finish, if you want to opt out of notifications that are sent by default after each send in a series is completed.

Review the list of send dates at right to make sure it will fire when (and only when) you intend; and click Save.

Finally, click Start recurring mailing, confirm everything on the haiku screen, and you'll see a confirmation message.

A scheduled email will appear in the drafts list. You'll see two icons next to the subject line: a clock indicating it's scheduled and an arrow indicating it's recurring. Click the mailing's title to get access to reports, or click Stop or Copy to stop or edit it. For more about maintaining your mailing now that it's launched, read on.

Editing

Editing a live recurring mailing is a little bit special: instead of modifying the active recurring mailing, you make a copy of it and launch that, and your new mailing replaces the existing one. While it's somewhat different from the non-recurring flow, it's still pretty straightforward.

Step by step:

  • Copy your existing recurring mailing.

    A draft should appear in the list, with an arrow indicating it's a recurring draft.

  • Edit the content and targeting.

    Check previews, get proofs, and so on as you did when you were first setting up the mailing (see above).

  • Click Start recurring mailing and confirm when ready. Until you confirm, the old content will continue to send.

  • Edit the schedule, if needed. Schedule edits, unlike content edits, take effect as soon as you submit them, so be careful.

Again, content edits don't take effect until you start the new recurring mailing. Your old mailing content keeps going out while you work on your new draft.

If you want to make sure nothing goes out while you edit (for example, if the old content is glitchy or inappropriate), use the Stop link in the mailing list instead of the Copy link. The scheduled mailing for the next recurring send will be set back to draft status and the series will be set to stopped. You can restart the series from the Proof and Send screen on the recurring mailing.

Hiding an active recurring mailing will also stop the series, but it may have unintended consequences; we recommend stopping the series first.

Terms and Data Capture

In order to fully understand recurring mailings (and the reports on them), we need to go into a little more detail about how ActionKit keeps track of them. What we call a "recurring mailing" has a few different pieces, and these are the terms we use for them:

  • Recurring series (or 'schedule') - This stipulates when the mailing will go out.

    Only one mailing on a given schedule is ever active at once - when you launch a new mailing on a schedule, the old one is stopped. Edits to a schedule take effect immediately when you hit Save.

  • Recurring mailing - This is the mailing you edit; it has the master version of your content and targeting.

    Once you launch a recurring mailing, you can't change it - instead, you copy the running recurring mailing, edit it, then launch your new mailing. The old version is replaced and has its status set to 'stopped' automatically.

  • Recurring sends - These are copies of your master mailing, for each time the message is sent.

    It can be confusing that each send has its own mailing ID, but that makes a lot of the click/open/etc. tracking possible. You'll normally see the next send of each recurring mailing in the scheduled drafts list, and many sends in the history of sent mailings.

If you're writing queries, here's where you find each of those things in the database:

  • Recurring series are stored in core_recurringmailingschedule and identified by a recurring_schedule_id.
  • Recurring mailings are stored in core_mailing with status="recurring" (or "stopped" if they've been replaced or stopped). A recurring_schedule_id links them to their schedule.
  • Recurring sends are stored in core_mailing with status="sent" or "scheduled". A recurring_source_mailing_id links them to the master recurring mailing they were copied from, and a recurring_schedule_id links them to their schedule.

Reports

When you click a recurring mailing's subject in the Mailings tab, there are links to ActionKit's default recurring-mailing reports. Those are:

By default, the subjects and clicks reports only run against the latest mailing (i.e., the latest version of the content), not past mailings in the series. So, if you've recently replaced your mailing content, these results won't include sends with your old content.

Sometimes, you may want results to include old versions. For example, maybe your old versions are nearly identical to the new. In that case, links to reports covering all versions should appear beneath the main list, or you can manually blank out the click/subject report's mailing_id parameter by running them through the Reports tab (or tweaking the URL in your browser). If you want clicks-by-link/subject line reports covering a particular set of mailings but not all of them, you can also use a semicolon (;) separated list of mailing_ids.

Managing Your Mailings

There are several features designed to assist you with managing your mailings:

Mailings Dashboard

Use the links across the top of the Mailings tab to see:

  • Summary: Recent mailings divided by status (Current drafts, Drafts rebuilding mailing sets, Scheduled mailings, and Sent mailings), with summary data for each mailing.
  • Drafts: Draft mailings that aren't scheduled to send.
  • Rebuilding: Drafts with a target set that is currently rebuilding.
  • Models: Models are similar to drafts, but can't be sent directly; instead, you can copy a model to create a new draft with similar properties.
  • Scheduled: Drafts scheduled to send once or on a recurring basis.
  • Sent: Sent mailings, with the most recent mailings first.
  • Recurring Sent: Recurring mailings that were sent, with the most recent mailings first.
  • A/B Tests: Mailings that were A/B tested against each other, if there were any tests.

Select Browse All at the top of the Mailings tab to see the summary data for all mailings, or use Search and Filters to display a smaller set of mailings.

Click the mailing subject line to view the detailed statistics for sent mailings.

Summary Data

The following information is displayed for each mailing on the dashboard.

Drafts

On the left:

Subject line (first entered if there are multiple for the mailing).

Below this, on one row:

Notes (if applicable) Mailing ID Test group information (if applicable)

And a link to open More information, including any associated tags, and timestamps for the last edit and last target set rebuild for this mailing.

On the right:

Action links (Edit, Copy, Hide for a standard draft).

Below this:

A mailing count. Double click on any number to update it. For drafts the mailing count shows the number of recipients based on the current targeting criteria. For sent mailings the mailing count shows the number sent, over the number of users identified pre-send based on the targeting criteria. If the count is less than you expected, check for a failed count.

You may also see a link to Rebuild Now if the mailing requires a target set rebuild before send.

Scheduled mailings have an additional section below the count that shows when the mailing is scheduled to send and if the target set will also rebuild at send time.

Scheduled mailings have an action link to Cancel, but not to hide. If you cancel a scheduled mailing it becomes a draft which can be hidden.

Sent mailings show a count of mailings sent over the projected count as well as open and click rates. While the mailing is sending, the open and click rates are based on how many emails have been sent, not on the total target audience.

The mailing status is also shown (Sending, Died, Stopped, or Completed) with the timestamp.

If the mailing send failed for particular users, you'll see a count for failed in the status column which links to the section in the individual mailing report that details what information was missing for the users. Read more about failed deliveries.

Using the Browse All Listing

The Browse All button displays the full list of all mailings. Alternatively, use the search box or the built in filters to view a list of specific mailings on this screen.

This screen displays the same Summary Data as the dashboard except the status column indicates whether it is a draft, scheduled, or sent mailing. Recent change timestamps are not displayed for drafts.

From this listing you can:

  • Filter mailings by status (draft, scheduled, completed, recurring, etc.), send start, and tag using the toolbar on the right.
  • Search by key word and sort the list by specifying Order By and Descending or Ascending and clicking Search.
  • Stop a mailing while it's sending; the stop link disappears when the mailing has been sent to everyone.
  • Show hidden or disabled mailings by clicking Show Hidden.
  • Remove a listing by clicking Hide.
  • Create a new draft mailing by coping an existing mailing.
  • Bulk edit mailings to show hidden mailings or add/remove tags from mailings.
Bulk Editing

For Mailings, you can show hidden mailings, add and remove tags from mailings in bulk.

To bulk edit:

1 From the Browse All screen (or from the Event List screen for events), click on the “Bulk Edit” link in the top left next to “Show Hidden”.

2 Choose the items that you want to apply the action to -- you can click to select specific items, or select all items visible on the screen.

3 Click the Save button, review the count of objects to be changed, and confirm.

You’ll then see a reportback with the number of changes actually made. This may differ from the preliminary count if, for example, an object you try to apply a tag to already has that tag.

../_images/1_bulk-editing.gif

Auto Exclude

Auto excludes is an optional feature that you can turn on and configure in your instance. It's designed to help you ensure that each subscriber gets no more than one regular mailing on a given day. This setting changes how you set up and manage drafts and it's only relevant if your goal is to avoid overlap, so it won't make sense for every organization. If you want to send people multiple emails per day (when they've subscribed to more than one newsletter, say), or if you don't usually have more than a couple mailings on any given day, it might not be for you. But, if you try to mail most users once a day and have a lot of mailings to manage, you may want to consider enabling auto excludes.

Read more about setting up and using auto excludes.

Models

Model mailings are drafts that you've designated as templates to be copied as the basis for other mailings. Model mailings can not be sent.

You may want to create different models for particular kinds of mailings to save time and help enforce business rules. For example, if you have a C3 and a C4, you might have a model fundraising appeal for each where you've selected the proper from line and wrapper and limited the targeting to the correct list. Later, you can copy the appropriate model to create a a draft that shares those common elements, edit it as needed, and send it normally.

To designate a mailing as a model simply click the Is Model checkbox.

Note

Only staff users with the Mailings - Edit plus Model Mailings permission and superusers can create and edit model mailings. The checkbox to designate a mailing as a model will not show up for other users.

Tags

Tags are words or phrases you can associate with a mailing. The tag list is the same for pages and mailings, but unlike with pages, when you associate a tag with a mailing no users are associated with the tag, whether or not they receive the mailing.

Tags are used to categorize your mailings. Tags are displayed on the Mailings Tab and the Browse all listing, and you can filter by Tag. For example, you can quickly view the list of all the Mailings you have created for a particular campaign.You could also write a custom report analyzing mailing performance by tag.

To edit, add, or hide a tag, see Working With Tags.

Mailing Jobs

A job is created each time you create or rebuild a mailing’s target set. The Manage jobs button at the bottom of the related tools list shows a count of your active jobs. The count is refreshed every 15 seconds. If there are 3+ jobs running, you'll see a red exclamation point. Click the button and a list of jobs (also refreshed every 15 sec) pops in above the list of mailings. You can only kill all of the mailing count jobs at once because of the possible dependencies between mailings. The job list includes any re-engagement jobs you have running.

https://s3.amazonaws.com/clientcon/images/editor-2018-01-30-2.png

Testing Your Mailings

Testing is supported in the following ways:

Subject Line Testing

A compelling subject line can significantly increase your action rates. You can easily run a test to see which of two or more subject lines (or subject line and preview text combinations) performs better with your list and send the winner to everyone who didn't receive the test.

1 Create a draft from the Mailings Tab.

2 Enter two or more subject lines.

Click the plus sign (+) to add more subject line fields or copy-and-paste multiple lines into a subject field to create them in bulk. Optionally, enter preview text for your subject lines.

3 On the Target screen, include everyone you want to receive the winning mailing.

  1. Use the Limit field to set the size of your test. For example, if you intend to email your full membership of 500,000 users, you might limit to 50,000 users for the test.
  2. Leave Sort set to Random. ActionKit will pull a random sample of users who meet your targeting criteria. In the example, ActionKit would pull 50,000 members at random to receive the test.

4 Send your email following the process in Proof and Send.

5 Monitor the results by subject line using the Mailing Report. Remember to look at unsubscribe and spam rates as well as action rates.

6 If there's a clear winner before your test is done sending, you can stop the mailing using the stop link next to the mailing under Sent on the Mailings Tab. The stop link is only seen while the mailing is still sending.

7 Click the winning subject line in the Mailing Report.

8 Clicking a winning subject will:

  1. Create a copy of the mailing with only that subject and preview text.
  2. Target everyone you selected in step 3 above except those who received the test mailing. If your test mailing was part of an A/B Test Group, the other mailings in the test group will also be excluded from the new mailing.
  3. Drop the limit.
  4. Request a new count.
  5. Show you the final count and mailing.

9 Click Send and your email will be sent to anyone in your selected audience who didn't receive the test Mailing.

You can also automate the steps from 5 on, by enabling automatic subject line testing on the targeting screen. If you use the automated testing, you can still cancel it any time or pick a winner manually. Manually picking a winner cancels any pending automatic test.

A/B Test Groups

Test groups allow you to group two or more mailings to make head-to-head testing easier and more foolproof. Using a group helps protect against common testing mistakes by making sure the mailings' targeting criteria and rough size match, that the groups don't overlap, and that they're launched at the same time. They also help simplify the process by letting you review and launch the whole set of mailings from one screen, and use a few clicks to compare the mailings with statistical details and launch the winning mailing.

You can still run manual tests, using the Compare Mailings report to compare performance. In some cases this is the better approach. Test groups only make sense when mailings' targeting, size, and launch time all match: they're not designed for testing three petitions to three different list segments, or testing sending the same message on different days of the week. Groups also aren't available for petition delivery mailings or recurring mailings. And for small variations in message content, it may be simpler to create your own test using the mod filter.

To start, click Create A/B Test Group on the Mailings dashboard. Enter a name; click drafts you'd like to include or, if you'd like ActionKit to create blank drafts for you, enter how many you want.

When you edit the targeting of any draft in the group, it will change targeting for all of them. When you pick a user limit, note you're limiting how many users each Mailing in the test can hit--it's not an overall limit for all mailings combined.

After you've created your test and entered final content, then click Proof and Send Test Group from any group member's Proof and Send screen (or click "Launch Test" in the drafts list). You'll see basic information on each draft and previews; if you see you need to make edits, click the title of any draft to go back to it. You can click "Edit test group settings" at the top of the page to add or remove drafts, change the title, or cancel the test. (You can access the same settings from the bottom of the targeting screen of any Mailing in the group.)

When everything's ready, scroll down to the bottom of the targeting screen. The system will check for obvious problems (e.g query not built, missing content, etc.) and hide the Send button if it finds any. When ready, click Send (or schedule, if applicable), take a moment for artistic appreciation of the haiku, and confirm. Even if you set up an immediate send, the test drafts will show in the Scheduled section on the Mailings Tab, sometimes for up to ten minutes.

Click the Test Results link on the dashboard to see the Compare Mailings report comparing the drafts. In the "results summary" view, you can see whether any draft is significantly ahead of the others (indicated by other drafts' numbers appearing greyed out) and see 95% confidence intervals for opens, clicks, and actions. (You might have to make a decision when without a single significant winner sometimes, but it's good to be aware of the uncertainty.)

Clicking one of the buttons in the Select Winner column of the report will load a copy of the winning Mailing, which excludes all of the test mailings and removes any limit on number of users. You can also click on a subject to see a mailing's individual report, or go back to the content-review screen you launched the test from. From an individual mailing report, you can click on a subject to choose a winning subject and winning mailing at the same time.

Those are the steps to running a test with test groups.

Other information you might find useful:

In test groups, some things work differently from usual, to keep mailings matching each other. Again, editing one Mailing's targeting changes targeting for the other mailings in the group, too. Test mailings' targets also won't overlap each other regardless of whether you use auto excludes, and will go to similar groups even if you use a non-random ordering like ZIP Code.

If a test Mailing stops early because of an error or is killed, you can reload it, and the reloaded mailing will assume the original mailing's test group targeting. Things work a little differently in this mode: you can't add or remove drafts from the test, and changes to the reloaded mailing's targeting won't (of course) affect the other sending drafts.

Internally, ActionKit targets test-group mailings using the MySQL MOD operator. Each group uses an arbitrarily-picked prime number, and each mailing in the test gets a WHERE condition like WHERE user_id MOD [prime] MOD [number of drafts in test] = [number of this draft]. You can see a particular draft's WHERE condition in its targeting summary. It's usually simpler to do reporting using mailing IDs, but you can also use the MOD expression directly for analysis.

Testing With Mod Filter

The approach below can be applied to bulk mailings or confirmation emails.

When creating your mail message, use a "mod" filter for basic A/B testing. You'd do something like this in the body to send different content to even and odd-numbered users:

{% if user.id|mod:2 %}
  Piece of content #1
{% else %}
  Piece of content #2
{% endif %}

Or for more than two different messages, use the following code to send different content to every third user:

{% with user.id|mod:3 as test_group %}
  {% if test_group == 0 %}
     Piece of content #1
  {% endif %}
  {% if test_group == 1 %}
     Piece of content #2
  {% endif %}
  {% if test_group == 2 %}
     Piece of content #3
  {% endif %}
{% endwith %}

Use different links in each message to monitor performance based on which content a user received. View the Clicks-by-link section of the Mailing Report.

Deliverability And List Hygiene

Mailing List hygiene refers to the practice of "cleaning" your Mailing List by removing inactive and undesirable email addresses, in order to improve your email deliverability for the remaining active and desirable addresses.

Email deliverability is increasingly based on sender reputation. ISPs are looking at the same kind of stats we do, like open and click rates, plus some additional information that they have that we don't. The more your users interact with your email the better your reputation, and the more your mailings reach your users' inboxes in a timely manner. Sender reputation attaches to the combination of your IP address and domain name.

Sending emails that are ignored costs you because ISPs use that in calculating your sender reputation.

And long-time inactive users aren't bringing you much benefit. One large client found that users who had last opened or clicked a mailing in the last year had a 31% open rate. Those who opened or clicked in the last 12 to 24 months had a 10% open rate. The open rate dropped to less than 1% past 24 months. We encourage you to analyze your own list because these rates may vary, but the trend has been consistent.

Also, long-time inactive emails are sometimes turned into spam traps by the various ISPs. Spam traps never open your emails, and sending to them always hurts your reputation.

List hygiene can improve your deliverability, increase total actions and may even decrease your monthly ActionKit bill.

You can take advantage of our Re-engagement Tool and Blackholing Email functionality to help manage your list hygiene.

Creating a Re-engagement Process

Some list hygiene steps are automatically handled by ActionKit, like unsubscribing users whose email addresses bounce as undeliverable.

We also encourage you to establish a re-engagement process, where you:

  • Establish criteria to identify inactive users.
  • Add those users to a special re-engagement list.
  • Exclude that list from regular mailings.
  • Send those users a few hand-picked mailings to prompt them to open or click.
  • If they don’t re-engage, unsubscribe them.

ActionKit includes tools to help you automate this process.

To configure and enable ActionKit's re-engagement feature, click the Re-Engagement link under List Hygiene in the sidebar on the right on the Mailings Tab.

Defining Engagement Queries

You want to identify inactive users to move to your Re-engagement list. To do this, you'll first identify active users.

Click on Engagement Queries and select one or more query reports which will identify active users. You'll need to decide which criteria your organization will use to determine whether users are active, but typical choices include users who have clicked on a mailing in the last few months, or users who have made a donation in the last year.

We've included some default queries which you can use, edit or remove:

  • New-to-database users {days: 180}
  • Recent Mail Openers {days: 180}
  • Recent Mail Clickers {days: 180}
  • Recent Mail Actions {days: 180}
  • Recent Donors (Last N Days) {days: 180}

The result of all engagement queries are OR'd together and checked against the list of subscribed users. This means that a subscribed user who meets the criteria of any one of your queries is considered active.

You can choose from any existing query reports which have the mailer tag, or press the green "+" symbol to add a new report with your own custom logic. Remember when adding new query reports that they must have the mailer tag and must return a single column with a set of user IDs.

Note

The default queries purposefully only count users who took action from a mailing as active, as that proves that an email address will respond to a mailing. You may want to alter this to count non-mailing actions (eg, actions from Facebook or imports) as signs of engagement as well, but just be aware that in doing so, email addresses that do not respond to being mailed may continue to receive your normal mailings.

Also note that newly created users are protected from being moved onto the re-engagement list (because of the "New-to-database users" query included by default), but that there is no default protection for users who may have resubscribed to your list.

Checking Engaged User Counts

Once you have defined Engagement Queries you can check the count of users they will match by clicking the Check count now link on the Status line.

The counting process may take a while, depending on the size of your user list and the complexity of the queries you've selected. Reload the page as needed, or return to it after some time has passed in order to see the numbers of engaged and unengaged users produced by the queries you have selected.

The engaged count plus the unengaged count will equal the total number of mailable users in your database.

Re-engagement Settings

The next step is to define what should be done with the unengaged users you just identified.

Click on Re-engagement Settings to choose which Mailing List you want to move inactive users to. (The first time, you'll probably want to create a new Mailing List for this as described in Mailing lists).

In the Settings you can also choose to enable automatic list migration and unsubscribing users.

List Migration

You can run list migration manually or automatically to move users to and from the re-engagement List.

During a list migration, all of your selected engagement queries are run, and the results are compared to the list of subscribed users. Any subscribed users who don't appear in the engagement query results will be added to the re-engagement list, and any users who do appear in the engagement query results will be removed from it.

Users are not unsubscribed from the lists they were previously on (unless you've enabled automatic unsubscribes and the requisite number of days on the re-engagement list have passed) -- instead, they are simply added to the re-engagement list so that you can exclude them from your general mailings.

These changes only occur when a list migration process is run, either manually or automatically. We recommend automating list migration. If you choose to do this manually, be sure to prompt a list migration before mailing the re-engagement list. Otherwise, any users who took action (possibly prompted by an earlier re-engagement mailing) will still be on your re-engagement list, considered unengaged.

Manual

You can prompt the process to run immediately by clicking the Start migration now link on the Re-engagement Overview screen.

The migration process may take a while, depending on the size of your user list and the complexity of the queries you've selected. Reload the page as needed, or return to it after some time has passed in order to see the numbers of engaged and unengaged users remaining after the process has completed.

Automatic

To enable automated processing, click the Automatic list migration enabled checkbox on the settings screen.

When automatic list migration has been enabled, a scheduled service will run the list migration process every day.

The Status section on the Re-engagement Overview screen shows the next time the list migration process is scheduled to run, as well as the last time it ran successfully.

Auto Unsubscribing Users

After you attempt to activate the users on your re-engagement list a certain number of times, you should stop mailing them. We suggest unsubscribing them entirely at this point so no mistakes are made.

You can automate the process of unsubscribing these users by clicking the Unsubscribe users automatically checkbox and adjusting the Unsubscribe users after days on list setting.

Set the number of days based on your planned number and timing of re-engagement mailings.

Each time a list migration occurs, any users who have been on the re-engagement list for more than the specified number of days will be unsubscribed from all mailing lists.

If you want to immediately unsubscribe inactive users (e.g. everyone on your re-engagement list) at any point, turn on the Unsubscribe users automatically option and set the "after days on list" value to zero, then prompt a list migration.

Re-engaging the Unengaged

Once you have a re-engagement list set up, there are two sides of putting it to use: firstly, exclude them from most general mailings you send, and secondly, send them selected re-engagement messages.

Excluding From Mailings

To exclude users on the re-engagement list from new mailings by default, click on Re-engagement Settings, and click the Exclude re-engagement list from default mailer targeting option. With that in place, new mailings you create will start out with targeting that excludes users on that Mailing List.

Sending Re-engagement Mailings

To send re-engagement messages to that list, compose a Mailing and edit the targeting, removing your re-engagement list from the exclude groups and adding it to the mailing criteria instead.

Generally you would send your most successful mailings to the re-engagement list, with messages that have proven to draw users' attention. Since these users have been ignoring even your most successful mailings, you might consider alternative approaches as well, like subject lines specifically designed to provoke an open or click, or a very short message, or even just a "Do you still care about this issue".

If users on the re-engagement list take an action in response to a mailing that meets your Engagement Query criteria, they will be moved off of the re-engagement list the next time that list migration is run. Remember you have to prompt list migration if you didn't automate it.

If users ignore all of your re-engagement messages, and linger on the re-engagement list for an extended period of time, it is unlikely that they will ever take further action, and they can be safely unsubscribed from your lists.

Setting up a Recurring Re-engagement Series

If you want to automatically send one or more messages to everyone who is placed on the re-engagement list, you can use the same approach as described in the Welcome Series FAQ. However, note that you would use the new_to_list query to match users who have recently been added to your re-engagement list, rather than the new_to_database query.

For example, you could set up two recurring mailings, one that automatically mailed people one week after they were added to the re-engagement list, and a second that mailed people one month later.

Migrating Previous Suppression Groups

If you have a set of users who you have been suppressing from your mailings using exclude queries that pre-date the introduction of this feature, and would like to migrate them into your re-engagement list, you can do so before setting up your ongoing re-engagement plan.

First, define a new query report that matches all users except the ones you have been suppressing, and configure the re-engagement tool so that this new query is the only active engagement query. If you would like these users to be unsubscribed immediately, also turn on the "Unsubscribe users automatically" setting and adjust the "Unsubscribe users after days on list" setting to zero. Then allow the migration process to run, by using the "Start migration now" link or by waiting for the next daily run.

When processing of your previous suppression group has completed, you can update your settings to reflect your new re-engagement process and allow it to continue running automatically.

Re-engagement Data and Reports

The Re-engagement Activity by Date report shows a count of users moved on and off the re-engagement list for any day with activity, along with a count of users unsubscribed.

The Activity Rate By Last Previous Action report shows a count of users who took action in the last 30 days, broken down by number of months since their last previous action.

Total Subscribed and Disengaged Users shows a count of your mailable users plus a count of all users who were unsubscribed through the re-engagement process. This number shows what your total mailable list size might be on any given day without a re-engagement program.

Email Productivity By Week shows your total actions and an action rate as a percentage of sent mail by week. As a result of a re-engagement program you are likely to see an increase in this action rate as a result of an improved sender reputation.

You can find related data in the following tables:

  • core_reengagementlog: shows daily counts for users engaged and unengaged per the most recently run count, added to the re-engagement list, removed from the re-engagement list, and unsubscribed through list migration.
  • core_subscriptionhistory: There's a new core_subscriptionchangetype for 'unsubscribe_reengagement'.

Sending domains

When you start using for ActionKit, we choose a single domain to use for your outbound email. This is called your sending domain. If you use an unknown domain in a From line, ActionKit will replace it with your default sending domain so the message is sent, and will use the original From line as the Reply-To header.

Sticking to a single From domain helps your deliverability. ISPs treat your domain as part of your identity as a sender. Splitting your email stream across domains dilutes your reputation, and a new domain is likely to be treated more harshly, like an unknown sender. Furthermore, varying the From domain doesn't necessarily help branding much: the email address in the From line isn't one of the first things most users read. The rare times you want users to reply to a custom address, Reply-To will do what you need.

If, in spite of the deliverability risks, you need to change your default domain or add another domain, let us know. You'll need to set up some DNS records and we'll need to make some configuration changes for you.

Mailing Speed

Our target mailing speed is a minimum of 1 million messages per mailing per hour (278 messages per second), but most mailings send faster than that. If mailings are running more slowly than you'd like, you can take steps to speed up sending.

1 Optimize your mailing with variables. Each time you use a snippet, it makes a call to the database. The {% with %} tag can save the result of that database call and show it multiple times in your mailing in the format {% with snippet.name as variablename %} where snippet.name is the snippet you're saving and variablename is how you'll reference that snippet later.

{% with donations.highest_previous as hpc %}
  {% if hpc > 500 %}
     Something that happens when highest previous gift is over 500...
  {% endif %}
{% endwith %}

2 Our send speed is per mailing per hour, with up to four mailings going at a time for each sender. If you split a big mailing into two, you can double your speed.

3 If you still feel like you need more zoom, we can offer upgraded send instances for a fee. For most senders, the above tips are enough.