Email Templates

From invoice receipts to declined payments, Recurly can email your subscribers on your behalf. The emails can be customized and individually enabled. Emails can only be sent to accounts with an email address. If an account does not have an email, Recurly will only send the email to you.

Email Types

By default Recurly will send emails for the below actions. Individual emails can be disabled in the email’s Edit Settings page. Emails settings and templates are global and cannot be customized on a per-plan or per-user basis.

New Subscription

Sent when the customer successfully signs up or a future start date subscription is activated. This initial email includes the customer's first invoice.

Subscription Changed

Sent when a customer's subscription is changed. When a customer's subscription is changed "at renewal", the email is not sent until the subscription renews and change is made.

Subscription Canceled

Sent when a customer's subscription is canceled. The customer will receive the Subscription Expired email when their current bill cycle ends and the subscription is terminated on their account

Subscription Canceled Due to Non-payment/Past-due

Sent when a customer has been completely through the dunning process without making a successful payment. The subscription is terminated at this point

Subscription Expired

Sent when a subscription is either immediately terminated or when a canceled subscription has reached the end of its bill cycle.

Payment Receipt

Sent whenever payment is successfully processed through Recurly. This email will not be sent for $0 invoices

Payment Declined

Sent whenever a payment is attempted and fails. After the initial failure, this email will be sent additional times according to your Dunning Management settings.

Password Reset

Sent when a customer accesses your hosted page and requests a password reset.

HTML Emails

By default, Recurly sends both a plain-text and HTML email to your customers. Your users’ mail client will display the HTML version if it can, otherwise it will fall back to the text-only version. We recommend customizing both templates to suit your needs. However, you may also choose to disable the HTML version on a per email basis. This setting can be found when editing the settings for an email template.

Email Parameters

Recurly allows you to fully customize your email templates. You may use the following placeholders in your templates and Recurly will replace them with the appropriate parameters. This allows you to customize the emails based on the message type and recipient.

Company Fields

{{company_name}}

{{company_email}}

Subscription Plan Fields

{{plan_name}}

{{plan_code}}

{{plan_description}}

{{plan_per_interval}}

The plan's renewal interval, e.g. "per month" or "per 2 weeks."

{{plan_trial_interval}}

The plan's trial interval, e.g. "1 month" or "2 weeks."

Account Fields

{{account_code}}

{{account_username}}

{{account_first_name}}

{{account_last_name}}

{{account_full_name}}

{{account_company_name}}

{{account_email}}

{{account_hosted_maintenance_url}}

URL with embedded authorization token to automatically log into your hosted account management page.

Billing Info Fields

{{billing_cc_type}}

Credit card type, e.g. Visa, MasterCard, etc.

{{billing_last_four}}

Last 4 digits of the credit card number.

{{billing_first_name}}

{{billing_last_name}}

{{billing_address1}}

{{billing_address2}}

{{billing_city}}

{{billing_state}}

State or province.

{{billing_zip}}

Zip or postal code.

{{billing_country}}

{{billing_full_address}}

{{billing_ip_address}}

Account's IP address during the last billing info update.

{{billing_vat_number}}

Account's VAT number.

Invoice fields

{{invoice_number}}

{{invoice_date}}

Date the invoice was created. This may be different than the {{transaction_date}} if the initial transaction failed. {{transaction_date}} may be empty if there is no transaction required for the invoice.

{{invoice_subtotal}}

Total amount of the invoice before payments are applied.

{{{invoice_discount_amount}}}

Requires 3 brackets. Dollar amount of discount applied to invoice.

{{invoice_total_paid}}

Total amount of payments applied to the invoice.

{{invoice_total_due}}

Total amount outstanding on the invoice. This will be zero if the invoice is paid.

{{#invoice_line_items}}

Requires leading pound sign. Collection of line items on the invoice.

Line item fields

{{line_description}}

{{{line_amount}}}

Requires 3 brackets. Line item total amount.

{{{line_unit_amount}}}

Requires 3 brackets. Line item unit amount.

{{{line_quantity}}}

Requires 3 brackets. Line item quantity.

Subscription fields

{{subscription_active?}}

Returns true if the subscription is active and has a next payment scheduled.

{{subscription_quantity}}

Subscription quantity.

{{subscription_quantity_is_one?}}

Returns true if the subscription's quantity is one.

{{{subscription_total_amount}}}

Requires 3 brackets. Subscription total renewal amount.

{{subscription_unit_amount}}

Subscription per unit amount.

{{subscription_has_trial?}}

Returns true if the subscription has a trial period.

{{subscription_has_no_trial?}}

Returns true if the subscription does not have a trial period.

{{subscription_expires_at}}

Date when the subscription expires if the subscription has been canceled.

{{subscription_current_period_started_at}}

Date when the current billing period started.

{{subscription_current_period_ends_at}}

Date when the current billing period ends.

{{subscription_next_payment_date}}

Date when the next payment will be charged.

Transaction fields

{{transaction_id}}

Transaction's UUID: 32-characters, alphanumeric.

{{transaction_amount}}

Transaction dollar amount.

{{transation_status}}

Transaction status (success/void/decline).

{{transaction_date}}

Transaction date.

Currencies and HTML encoded values

All parameters are HTML encoded by default when enclosed with two curly braces ({{). To properly display a foreign currency, the parameter needs to be enclosed with three curly braces ({{{)—this does not escape the text and allows currency symbols to be displayed properly for non-US currencies.

Boolean Sections

In the new subscription email, it might be helpful to customize the email depending on the presence of a trial. If the subscription has a trial, the email should read “Your credit card will be charged at XXX.” Whereas a subscription without a trial might say, “Your credit card was charged.” Here is an example:

{{#subscription_has_trial?}}
  Your credit card will be billed {{{subscription_total_amount}}} 
  when your trial expires on {{subscription_trial_ends_at}}.
{{/subscription_has_trial?}}
{{^subscription_has_trial?}}
  Your credit card was charged {{{invoice_total_paid}}}.
{{/subscription_has_trial?}

In the above example, the ^ character tests that the variable is false. The second code block is executed if the customer is not in a trial period.

This technique also works for testing if a variable has a value. You might not want to display a Next payment date if there is no next payment. This works as follows:

{{#subscription_next_payment_date?}}
  Next Payment Date: {{subscription_next_payment_date}}
{{/subscription_next_payment_date?}}

Invoice Line Items

The New Subscription, Invoice Receipt, and Declined Payment emails all include invoice information. Each invoice contains a collection of line items. To iterate over a list of line items, use the {{#invoice_line_items}} tag to start and {{/invoice_line_items}} to end the block. The template will repeat the text inside those lines for all the line items on the invoice. Here is an example:

{{#invoice_line_items}}
  {{{line_amount}}} -- {{line_description}}
    {{{line_date}}}
{{/invoice_line_items}}

Discounts

If you make use of coupons, you will likely want to display discount information on your invoices and hide it when the discount amount is zero. The code below will only display the discount amount if the invoice has a discount applied:

{{#invoice_discount_amount?}}
  Discount: {{{invoice_discount_amount}}}
{{/invoice_discount_amount?}}

Header and Footer

Recurly has a default header and footer for your HTML email templates. To use these, simply type {{> recurly_header_v2}} or {{> recurly_footer_v2}} in your email template. If you do not include these tags, the Recurly header and footer will not be applied to your emails.

If you would like to include your own customized header and footer, use {{{header}}} and {{{footer}}} respectively. By default, your custom header and footer will not be included in the email template.

Customizing the From email address

By default, emails are sent from the company’s email address. The from email address can be changed on a per email type basis in the email settings. A sender name can be included by formatting your From field as "Recurly Support" <support@recurly.com>.

Email Images

Images can easily be added into your email templates with just a bit of HTML. To include a company logo, edit your email header file to include code like this:

<body>
  <div style="border-bottom:1px solid #E8E8E8; margin:0px 14px;">
    <img style="padding:0px 0px 6px 0px;" src="http://mycompanylogo.gif"/>
  </div>

Resetting Your Templates

Occasionally, Recurly will update the email templates for all our subscribers. The updates will not affect your templates if you have any customizations. If your templates are not using the latest version of the templates, you may reset your templates back to the Recurly defaults. To reset your emails:

1. View your Email Template Details in Recurly

2. Click the Edit Template button below Email Settings

3. Scroll to the bottom of the page and look for a Reset Template button in bright red. The button is only visible if you have customized your template.

4. Click the button and agree to the reset.

5. Resetting your email template will not affect any customizations you have made to the HTML Enabled flag, TO, BCC, or subject line.

Email Deliverability

Recurly sends emails to your subscribers. To ensure the highest delivery rate for your emails sent from Recurly, we advise you to make the following changes to your DNS records so your email delivery rates remain high.

SPF Record

An SPF record tells other mail servers which domains are authorized to send emails on your behalf. Adding Recurly’s mail servers to your SPF records in DNS is very easy. This will let your customers’ mail servers know that emails sent by Recurly are being delivered for your domain. This dramatically increases the odds of a Recurly email being successfully delivered, instead of being quarantined in the spam folder. If you do not have a SPF record already setup for your domain it is very easy. You want to create two TXT records for the domain that have the following in it:

"v=spf1 include:spf.recurly.com ~all"
"spf2.0/pra include:spf.recurly.com ~all"

A full line would look something like this:

example.com. IN TXT "v=spf1 include:spf.recurly.com ~all"
example.com. IN TXT "spf2.0/pra include:spf.recurly.com ~all"

Example

If you also send email through gmail or Google Apps, your TXT record might look like:

example.com. IN TXT "v=spf1 include:_spf.google.com ~all"

It would look like this after adding Recurly’s entry in

example.com. IN TXT "v=spf1 include:_spf.google.com include:spf.recurly.com ~all"