Mailing Creation¶

Subject¶

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.

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.

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.

From Line¶

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.

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.

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.

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.

Body¶

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

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.

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:

• Donation Snippets
• Page Targets Snippets
• Edelivery Snippets
• Whipcount Pages

Web Viewable¶

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

• Check the box.
• Include a link to http://docs.actionkit.com/mailings/view/{{mailing_id}} with a note that users can click to view their email as a web page.

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.

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.

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.

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 Field¶

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.

Proofs¶

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

Includes and Excludes¶

Make selections in this section to build your target set.

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.
• Engagement Level: Sends to most engaged users first, then less-engaged users, and users with unknown engagement last. Uses ScorePool to determine engagement level.

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

Limits by Mailbox Provider - This allows you to set a limit on the number of users you send to from a mailbox provider, e.g. Gmail or Microsoft/Hotmail. This can be used to cap the number of emails you send to a provider to keep your volume consistent. (But keep in mind, this is a limit for the current mailing, not for a time period.) It can also be useful if you need to restart your warmup process for a particular provider while keeping the rest of your mail as is. The limits are applied to the sorted list of users, so if you sort by engagement level and limit by mailbox provider, you'll send to the most engaged users at that provider first.

This will never result in more users than the total limit you set for the mailing. Also, it is a limit, not a minimum, so it doesn't guarantee you will find that many users from that provider in your target set.

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.

If your mailing is a timed send (sending to users in their local time zone or scheduled), the Max emails/sec feature will be used to automatically distribute send times to obey the limit you set.

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.

For most mailing tests, the newer A/B Tests for Mailings will be easier to use, but test groups can still be useful for comparing mailings with very different contents.

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.

Preview Your Mailing¶

Click Preview, under Body within 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 Preview again 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, or the count is regenerating due to targeting changes, see Force a rebuild of the Mailing set.

You can enter the ID or email address of a user to see how the mailing will look for that user. This works even when your targeting is rebuilding. Keep in mind that previews for a user who isn't targeted by the mailing may not work correctly with certain snippets.

You can also choose which A/B test variation you want to preview.

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 A Rebuild Of The Mailing Set¶

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

If you change your targeting criteria, the current mailing set will be cleared and a new build will be started automatically. Even if you haven't changed the targeting, it's a good idea to generate a new count periodically by clicking Rebuild Now. 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. The mailing set information will be refreshed and you will be sent an email with the new recipient count.

Send Proofs¶

You can send proofs to yourself, other staff members and/or other email addresses. Proofs are copies of the actual mailing that will be sent to end users that you can review for misspellings or broken links or other issues.

When you send proofs, ActionKit creates a random sample based on the recipient group created on the Target screen. This way you can view proofs of the mailing for different users. If you have not yet saved a target set, the users will be selected from the full set of all your mailable users.

You can also send proofs of the mailing that particular users will see using the see proofs for particular users link. Enter a list of user_ids or emails to receive proofs for those users. This allows you to view mailings as they will appear to users meeting specific criteria. For example, if you want to see how your suggested ask will appear to donors with a large average gift, you can enter the user_ids or emails of 5 users you know meet that criteria. You can do this whether or not the specified user is in the target set for the mailing. This approach can be used to view a proof for a recurring series for which nobody meets the criteria today. We still recommend viewing and testing random proofs as well because you may encounter a problem you aren't specifically looking for.

You can send proofs from either the Compose or the Proof and Send screen. In both cases, the process is very similar:

1 At the bottom of the page, select the number of proofs you want sent to each proof recipient from the dropdown list, 1, 5, or 20.

2 Select the proof recipients by clicking in the to: box and selecting the name from the dropdown list. Repeat to select multiple reviewers. Hold down the command key to keep the list open while you select. You can also enter an alternative email address if you are on the Proof and Send screen.

3 Click And Save if you are on the Compose screen or Proofs if you are on the Proof and Send screen. The proofs will be sent.

If your mailing uses A/B testing, you can choose which variation you'd like to get proofs for, or let ActionKit cycle through all of them.

You'll always want to review at least one proof for appearance, typos, broken links, etc. Review multiple proofs if your email includes snippets. Always send yourself a final proof after making any changes just in case you accidentally broke a link or introduced a spelling error.

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.

The option Prepare messages immediately, rate limit send (recommended) appears if your mailing has a rate limit, and it is checked by default. This option will generate the messages for your mailing immediately, but will queue them as timed sends according to the rate limit you set. This is the best option for most mailings, as it will ensure that your mailing goes out on time and that you will be alerted immediately if there are any errors that would prevent the mailing from being sent.

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.