Customizing Content and Messages¶

Page Text Content¶

The following categories of Snippets are available for creating page content:

• Users
• Confirmation Email Snippets for Pages with Targets
• Whipcount page
• Thank you text
• Other Info
• Advanced Examples

Immediate Delivery Emails¶

Snippets available here are the same as the Snippets defined for Page text content.

After-Action Redirect URLs¶

Snippets available here are snippets associated with the user who just took action, and the action just taken.

For example, this includes {{ user.custom_fields.donated_2024 }} or {{ action.order.total }}

Confirmation And Notification Emails¶

The following categories of code Snippets are available for creating confirmation email messages:

Tell-a-friend Messages¶

Snippets available for Tell-a-friend composition are the same as the ones defined for Confirmation and notification emails.

User Snippets¶

All of the code Snippets in this category contain user fields for customizing your message. Most of the values are in the core_user table.

The User custom field tag inserts the value for any custom user field you've already created. Read more about custom user fields at custom user fields. You will have to edit the snippet to specify the field name and default value.

The User zip snippet does not contain a default value.

Snippets available for the Users category in mailings are the same as the ones defined for Pages > Users.

Landing Pages Snippets¶

The snippets in this category are used to insert the content from your Petition, Letter, Call, and other types of pages verbatim into your mailing.

Not all content types are available on all types of pages; see CMS Tables for reference.

Donations Snippets¶

Donation Snippets do not include default values. If you target non-donors with an email that has a donation snippet, ActionKit will skip users for whom the mailing would show a blank where the tag is. It's best to target only donors or use a conditional that only includes the relevant sentence if the user is a donor. It's also a good idea to view several proofs when using these tags since the donors are especially valuable to you.

Donation snippet calculations are standardized to match donation stats on the individual user record. Donations are complicated and they've changed over to time to account for various scenarios. The donation stats on the individual user record include only completed donations, include imported donations, exclude donations of $0 (like free product orders), and exclude any payments (first or later) toward a recurring donation profile for the one-time donation calculation and include them for recurring. These Snippets use all the same logic.

You can view the SQL used for the user stats.

The Suggested Ask snippet requires an algorithm for computing the ask value. You specify the algorithm by selecting the page that contains the algorithm in the Landing Page dropdown. Read more in Suggested Ask Rules.

Snippets that include only one-time donations are followed by (single). Those with (total) include one-time and recurring donations.

When using the recurring Snippets, if you have donors with more than one active recurring commitment, the tags will only reference the first recurring donation profile.

If you want to display some text in a mailing that's only visible to donors, you can also use ActionKit's donation snippets with the Django {% if %} syntax to check whether a value for the snippet exists, and then use that logic to display your message.

For example:

{% if donations.highest_previous_all %}
    P.S. Thanks for being one of our most wonderful donors!
{% endif %}

This message will only show for donors.

Events Snippets¶

Events Snippets include samples for recruiting attendees and reminding hosts and attendees about their upcoming event.

More than most snippets, these sometimes require you to set up targeting or landing pages before they work. See the Event mailings section for the necessary setup for recruits and reminders.

For more control over precisely which events are shown and how, see withevents and the events variable in the tags reference.

Page Targets Snippets¶

Target Snippets only apply when you're asking users to take action on a call, whipcount, letter, or petition page. If you use these Snippets, you must also select the page that identifies your targets from the Landing Page dropdown. For example, if the action you're asking users to take targets Senators, ActionKit will know from the page you select from Landing Page to insert Senators not Representatives.

Whipcount pages only: You can use the congress info Snippets for mailings related to whipcount pages but remember that whipcount pages display all targets (whether or not the user lives in-district).

To use these Snippets in mailings that target constituents and non-constituents, you have to remove the {% requires_value targets.count %} and use conditional logic to show non-constituents something useful:

{% if targets.count %}
<div> Call: <ul>{% for target in targets.targets %}
<li>{{ target.title_last }} - {{ target.phone }} {% endfor %}</li> </ul> </div>
{% else %}
<div>Not a constituent? Call anyway!</div>
{% endif %}
<p> LINK TO YOUR WHIPCOUNT PAGE</p>

Other Info Snippets¶

Link Snippets¶

These Snippets allow you to change ActionKit's default treatment of links in your mailings.

In addition to the click to insert Snippets, you can append nosig=1 to your URL if you've created a petition and enabled one-click, but you want to disable one-click in a particular mailing without disabling user recognition and tracking.

Advanced Examples Snippets¶

You can also use other fields as triggers based on the Snippets in this category. For example, you could replace state in the Localized content snippet with another user field (like city, country, zip or first_name). If your conditional doesn't appear to be working make sure you've got the correct field name. For example user.first_name is right; user.name isn't.

E-delivery Snippets¶

These Snippets are part of our e-delivery system for petition signatures or letters. To use these, you need to have set up a petition delivery job, the job needs to have at least one target with more than two signatures, and you need to select the relevant page from the Landing Page dropdown on this screen.

The Staffer/target name snippet inserts the legislative director's name if you're targeting a federal legislator; otherwise it inserts the target name. You can also insert the target's name using the "Sen. Smith" tag.

Always include the download link as this is the only way the legislative director or target will know where to pick up the signatures.

Merge File Snippets¶

Once you've uploaded a merge file (with a first column that will match the users you are targeting) and selected it on the Compose screen, the mailing will have Snippets available for including the columns for each user. 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 uploaded 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 could use the snippet {{ merge.paper }} in the mailing, and the paper that matches the user's zip code would be included. If the user's zip code was not included in the merge file, no value would be displayed. You can use a conditional block ( {% if merge.paper %} ... {% endif %} ) or a default ( {{ merge.paper|default:"your local paper" }} ) to avoid sending confusing messages.

Once you've associated a merge file with your mailing, the Snippets under "Merge Files" will use the actual columns from your uploaded file. The Snippets will includes a {% templatetag openblock %} requires_value %} to skip users without matches in the uploaded file.

To email users without matches, remove the requires_value tags that reference the columns that don't need to match. You should add a default filter or an if block to provide reasonable text for users without matching rows in the uploaded merge file.

Merge Query Snippets¶

If you write a merge query (with a first column that will match the users you are targeting) and select it on the Compose screen, the mailing will have Snippets available for including the columns for each user. 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" }} ).

Other Values¶

Other user-specific content may be available, even though we've only created built-in Snippets for the most commonly used fields. For example, you can copy and paste any of the following:

• /?akid={{ user.token }} - Let's say you want to thank users who take action on a petition page in your email, then ask them to contribute to the same campaign. You want the donation page to recognize the user. Just put the code above at the end of the link in your confirmation email.

• {{ user.location.us_county }} - Returns the user's county. user.location can be used to create Snippets from core_location data in mailings. Address information is in the core_user table, but some other geographic info like county is in the core_location table.

• {{ event.public_url }} - Returns a relative url like '/event/my_event_campaign_name/2117'. Add your domain in front for a fully-qualified URL. As an example, this has been used to put a Facebook like button on event attendee pages.

• {{ event.obj.starts_at }} - Returns an event's starts at datetime.

• {{ campaign.max_event_size }} - Returns the max event size set for the event campaign in the admin (if one was set). For example, use this to display the max in your event creation template.

• {{ campaign.all_events_count }} - Returns a count of all events for the campaign which haven't been deleted or cancelled. This matches the events count on the campaign dashboard.

• {{ campaign.open_events_count }} - Returns a count of open events for the campaign which have been approved and confirmed and haven't been deleted or cancelled. This matches the open count on the campaign dashboard.

• {{ campaign.signups_count }} - Returns a count of active (i.e. not cancelled) signups for events in the campaign. This matches the signups count on the campaign dashboard.

• {{ campaign.hosts_count }} - Returns a count of active (i.e. not cancelled) hosts for events in the campaign.

• {{ campaign.attendees_count }} - Returns a count of active (i.e. not cancelled) attendees for events in the campaign.

• {{ event.max_attendees }} - Returns the max event size set by the host for their event within a campaign. Could be used on an attendee sign up page. It should also work for true/false statements, as shown in the following code sample:

  {% if event.max_attendees %}
  This event can only hold {{ event.max_attendees }} people.
  {% endif %}
  

• {{ page.name }} - Returns the page's short name.

• {{ page.title }} - Returns the page's title.

• {{ user.stats.donated_amt }} - Returns the total ever donated by the user.

Whipcount Confirmation Email Example¶

The confirmation email can access the target the user called using the action.called.all snippet.

This returns a list (because the form supports submitting the results of multiple calls), so the snippet should either be used in a list:

{% for contact in action.called.all %}
{{ contact.target.title_last }} is {{ contact.response }}{% endfor %}

Or by accessing the first element in the list:

{% with action.called.all.0 as contact %}
{{ contact.target.title_last }} said {{ contact.response }}!{% endwith %}

Donation Confirmation Email Example¶

If you're using a standard donation page with monthly and one-time gift options, you can use a conditional tag in your confirmation email or on your thank you page to make your thank you message relevant for both donation types. These aren't click-to-insert Snippets, so you'd need to cut and paste them.

Here are two examples:

{% if action.orderrecurring %}
  Thanks for your recurring donation of ${{ action.orderrecurring.amount }}.
{% else %}
  Thanks for your one-time donation of ${{ action.order.total }}.
{% endif %}

— and —

Thanks for your {% if action.orderrecurring %}recurring
 {% else %}one-time{% endif %}
donation of ${{ action.order.total }}.

Also, you may wish to supply the donor with information about other contributions they've made. You might include a message about ongoing recurring donations.

For example:

{% if user.orderrecurring_set.active %}
  Thank you for your continued support:
{% for profile in user.orderrecurring_set.active %}
  ${{ profile.amount }} monthly
{% endfor %}
{% endif %}

This code will also work on a "thanks" followup page, but does NOT work in a mailing. See below for the equivalent snippet for a mailing.

Recurring Donation Mailing Example¶

The code for displaying a user's recurring donation information in a mailing is slightly different than in a confirmation mailing or page.

{% if user.recurring_orders.active %}
  Thank you for your continued support:
  {% for profile in user.recurring_orders.active %}
    ${{ profile.amount }} monthly
  {% endfor %}
{% endif %}

Grouping Snippets Into Categories¶

You can group custom snippets into categories by using a slash in the label, like this:

Greeting/Formal: Esteemed {{ user.first_name|default:"Recipient" }},
Greeting/Casual: Hey {{ user.first_name|default:"Buddy" }},

You can only group snippets one level deep.

Multi-line Snippets¶

You can create multi-line snippets which include return characters either by ending lines with a backslash or by inserting a \n at the appropriate place, as shown below:

Greeting: {% if user.first_name %}  \
        Dear {{ user.first_name }}, \
    {% else %} \
        Esteemed Recipient, \
    {% endif %}
Signature: -- Sincerely, Us. \n   Your friendly local advocacy group.