Using Template Files in ActionKit Mailings

The templating capabilities of ActionKit mailings are very powerful, and numerous organizations have built sophisticated examples that incorporate various user attributes to customize the message and calls to action. The enhancements made to custom mailing fields and email wrapper templates has made it easier to build flexible models that can be customized and reused over the course of months or years.

However, reusing those mailing templates still mostly depends on making a full copy of an entire mailing and then making changes to it — there isn’t a mechanism for building reusable components, or for separating out the “developer” portions of mailings from the “campaigner” portions, the way we do with ActionKit pages.

It was this thought that led me to wonder… “well, why can’t we leverage that same mechanism for mailings?” And it turns out that the answer is… we can.

See Also: This technique is related to the way sub-templates were created in the previous article about Building Sub-Templates for ActionKit’s include_tmpl, but it uses full-blown template files rather than strings. There are plausible reasons to think that this approach might be faster when used at scale, although I do not have performance metrics to demonstrate their relative speed.

Example

Let’s start with this simplified caricature of a donation mailing:

{% remember "5,10,15,20"|split:',' as amounts %}

<p>Dear {{ user.first_name|default:"Friend"|title }},</p>

<p> Please make a donation to support our work: <p>

<table>
  <tr>
    {% for amount in amounts %}
      <td style="padding: 0.5em">
        <a href="https://roboticdogs.actionkit.com/donate/funds?amount={{ amount }}" style="border-radius: 8px; background: green; color: white; padding: 0.5em 1em">Donate ${{ amount }}</a>
      </td>
      {% if not forloop.counter|mod:2 and not forloop.last %}
        </tr>
        <tr>
      {% endif %}
    {% endfor %}
  </tr>
</table>

<p>Thanks for all you do.</p>
	
<p style="background: #ffe; padding: 0.5em">
  This message assembled for you by flying monkeys.
</p>

We can generate a proof or preview to see the results:

(A real mailing would likely use a more sophisticated approach to selecting the suggested donation amounts, and would certainly have nicer content and styling, but this should be enough for an example.)

Creating the Components

In the ActionKit admin, click in to Appearance > Templatesets, find the “Original” templateset and click to copy it, giving the new version the name “Mailings.”

Now lets look for reusable components in our mailing and break them out as new template files:

calculate_amounts.html:

{% store as auto_amounts %}5,10,15,20{% endstore %} 
{% remember amount_str|default:auto_amounts|split:',' as amounts %}

draw_ buttons.html

<table>
  <tr>
    {% for amount in amounts %}
      <td style="padding: 0.5em">
        <a href="https://roboticdogs.actionkit.com/donate/funds?amount={{ amount }}" style="border-radius: 8px; background: green; color: white; padding: 0.5em 1em">Donate ${{ amount }}</a>
      </td>
      {% if not forloop.counter|mod:2 and not forloop.last %}
        </tr>
        <tr>
      {% endif %}
    {% endfor %}
  </tr>
</table>

assembly.html

{% with "[]"|load_json as creatures %}
  {% record "flying monkeys" in creatures %}
  {% record "rampant snails" in creatures %}
  {% record "languid sloths" in creatures %}
  <p style="background: #ffe; padding: 0.5em">
    This message assembled for you by 
    {{ creatures|shuffle|get:0 }}.
  </p>
{% endwith %}

Invoking the Templates

Upload these new files to your Mailings templateset, ensuring that you have the “add new custom templates” option checked, and then click the “Publish Changes” button to make them live.

Now we can revise our mailing to invoke these template files:

{% include "Mailings/calculate_amounts.html" %}

<p>Dear {{ user.first_name|default:"Friend"|title }},</p>

<p> Please make a donation to support our work: <p>

{% include "Mailings/draw_buttons.html" %}

<p>Thanks for all you do.</p>
	
{% include "Mailings/assembly.html" %} 

As expected, the resulting mailing includes the same features as our original version did:

Conclusion

I’ve just begun to explore the potential of this technique, but so far it looks quite promising.

Separating out some technically-complex portions of mailings can allow developers to create components that are maintained and updated separately from the contents of the mailings themselves.