The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Email Templates

From invoice receipts to declined payments, Recurly can email your subscribers on your behalf. The emails can be customized and individually enabled.

Email Types

Recurly can send emails for the below actions. Emails can only be sent to accounts with a valid email address, which cannot be "@test.com" or "@example.com". If an account does not have an email, Recurly will only send the email to the site billing contact.

Activate Account

Sent when a customer visits your hosted account management login page and requests to create an account for the email address they for their subscription signup.

Password Reset

Sent when a customer visits your hosted account management login page and requests a password reset.

Password Has Been Reset

Sent when a customer changes their password via reset link or while logged in. This email alerts them of the change in case they did not make it.

New Subscription

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

Subscription Change

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 Expired

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

Subscription Canceled

Sent when the customer selects to cancel their subscription. The Subscription Expired email would be sent when the canceled subscription reaches the end of its bill cycle.

Subscription Canceled for Non-payment

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

Trial Ending

Sent 3 days prior to the end of a customer's free trial as a reminder that their trial will be converting to a paid subscription. This is required by law in many regions. Can only be enabled if trial length is greater than 3 days (see below for more info).

Renewal Reminder

Sent 7 days prior to a customer's subscription renewal to remind them of their upcoming renewal. This is required by law in many regions. Can only be enabled if plan length is greater than 7 days (see below for more info).

New Invoice

Sent when a manual invoice is generated, or when a new subscription using manual collection is created on account. This email is only relevant to manual payments.

Invoice Past Due

Sent when a manual invoice reaches its net terms without recording a payment. After the initial failure, this email will be sent additional times according to your Dunning Management settings. This email is only relevant to manual payments.

Payment Confirmation

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. This email is not sent for failed signup attempts.

Payment Refunded

Sent when a customer's transaction has been refunded (either full or in part).

Payment Voided

Sent when a customer's transaction has been voided.

Payment Processing (ACH and PayPal eCheck)

Sent when a customer's invoice goes into a processing state. This email acts as the customer's authorization receipt and let's the customer know that their ACH or PayPal eCheck payment has been received and is in progress.

Refund Processing (ACH or PayPal eCheck)

Sent when a refund is issued and the refund invoice goes into a processing state. This email let's the customer know that they are receiving a refund, and it is in progress.

Gift Card emails

Recurly's support for Gift Cards includes support for several emails to either the gifter or the recipient. Learn more about Gift Card emails.

Please note that, unless you customize the content, these emails will always be sent in English.

Enabling and Disabling Email Templates

We offer two options for enabling or disabling email templates on your Recurly site. You have the option to make the setting on a site level for all of your plans, or on a plan-by-plan level.

To disable or enable any email template (except Trial Ending and Renewal Reminder) for your entire site, follow these steps. Note that this will affect all emails sent from your site:

  1. Navigate to your [Email Templates][11] page.
  2. Click Customize next to an enabled template, or Enable next to a disabled template.
  3. Click Edit next to Settings.
  4. Change the status dropdown to the status you want.

If you disable an email template at a site level, it will also be disabled for all of your plans.

If you would like to disable an email template at the plan level and continue to use the email template for other plans, follow these steps:

  1. Ensure that the email template is enabled at the site level on the [Email Templates][11] page.
  2. Navigate to Customization > Plans.
  3. Find the plan for which you would like to disable a particular email.
  4. Deselect the checkbox next to the email template you would like to disable. Note that the Renewal Reminder and Trial Ending Templates will only be enabled by default if the plan utilizes these emails.

Trial Ending and Renewal Reminder Emails

Trial Ending and Renewal Reminder emails allow you to automatically notify your customers before their free trial ends, or their subscription renews. Unlike other emails, these emails are enabled on a per-subscription plan basis by checking the respective Send Trial Ending Emails? and Send Renewal Reminders? checkboxes when creating or editing a plan (FYI, you will only see the option to enable Trial Ending emails if the subscription plan includes a free trial).

Trial Ending Emails

When activated for a plan, subscribers will receive a Trial Ending email 3 days prior to the end of their free trial. If a custom trial period is used, the trial period must be at least 4 days in length in order for the Trial Ending emails to be sent.

Renewal Reminder Emails

When activated for a plan, subscribers will receive a Renewal Reminder email 7 days prior to the renewal of their subscription. If a custom plan period is used, the plan period must be at least 8 days in length in order for the Renewal Reminders to be sent.

FAQ

What happens if you use the API to override the trial_ends_at date?

If the trial_ends_at date is less than 3 days in the future, the email will not be sent.

If I set a future start date, will the Renewal Reminder be sent?

Yes! As long as the future date is more than 7 days in the future.

If no email address is on file, will the site's default email be used?

Yes. Best practices would be to make sure you collect/pass the email address through to Recurly.

Can you set Renewal Reminders and Trial Ending emails via the API?

Not currently. Your only option is to use the admin console but this is something we are looking to add in the future.

If I enable the Trial Ending or Renewal Reminder emails on a subscription plan, will that effect existing subscribers?

Yes, as long as the existing subscription meets the criteria for one of these emails (3+ days until the trial ends for Trial Ending, or 7+ days until the next subscription renewal for Renewal Reminders) the email will be sent.

Can I include future invoice, subscription, transaction, etc information in the Trial Ending or Renewal Reminder emails?

No, the Trial Ending/Renewal Reminder emails will reference the information available at the time the email is generated. For example, if an account's subscription is scheduled to change at renewal, the emails will reference the current subscription information available on the account, not the new subscription information scheduled to take effect in the future.

Adding CC or BCC Addresses

Recurly gives you the option to add CC/BCC email addresses on any of the automated emails that are sent to your customers. This is especially helpful if you’d like to be notified of certain customer actions, such as when a customer cancels their subscription or when a payment is declined. You can add CC/BCC addresses via your admin console. To do so:

  1. Navigate to your [Email Templates][1] page.
  2. Click the Customize button associated with the appropriate email template.
  3. Click the Edit button.
  4. Add the appropriate email address into the CC Email Address field (you can add multiple email addresses separated by a comma).
  5. Click the Update Email Template button.

If necessary, you can then repeat these steps for any other email templates that you’d like to be copied on.
If you’d prefer to be BCC’ed on your emails, you can check the Send email copies as BCC’s box on the Site Settings page under Advanced Settings > Email Settings, then click the Save Changes button.

Customizing the From 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>.

Customization

Recurly allows you to customize your emails in a variety of ways, from adding images to inserting dynamic parameters.

Live Email Preview

NEW IN JUNE 2017. While you are editing an email template, you can click the Preview button while editing. This view will show you a live view of the edits you have made to the template.

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.

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.

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, Payment Confirmation, Declined Payment, New Invoice, and Invoice Past Due 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}}

Coupons and 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_has_discount?}}
    {{#invoice_discounts}}
    Coupon: {{coupon_code}} // Good For {{coupon_lifetime}}
    {{/invoice_discounts}}
    Discount: {{{invoice_discount_amount}}}
  {{/invoice_has_discount?}}

If you would like to display account active coupon redemption information, you can use the account_has_coupon and coupons parameters like this:

    {{#account_has_coupon?}}
     {{#coupons}}Coupon: {{coupon_code}} // Good For {{coupon_lifetime}}{{/coupons}}
    {{/account_has_coupon?}}

Note that Single Use coupons that have already been used will not be returned in this list. You will want to use the invoice_has_discounts example above to show any Single Use coupons used on the invoice.

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>

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.

Parameters

Company Fields

  • {{company_name}}
  • {{company_email}}
  • {{company_url}}
  • {{company_hosted_account_management_enabled?}}
  • {{company_hosted_account_management_full_access?}}
  • {{company_hosted_account_management_allow_pay_invoice?}}
  • {{company_address1}}
  • {{company_address2}}
  • {{company_city}}
  • {{company_state}}
  • {{company_zip}}
  • {{company_country}}
  • {{company_full_address}}
  • {{company_phone_number}}
  • {{company_vat_number}}
  • {{company_registration_number}}

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_address1}}
  • {{account_address2}}
  • {{account_city}}
  • {{account_state}}
    State or province.
  • {{account_zip}}
    Zip or postal code.
  • {{account_country}}
  • {{account_hosted_maintenance_url}}
    URL with embedded authorization token to automatically log into your hosted account management page. If hosted account management is set to "Guest View Only", this parameter will return the Guest View Edit Billing Info URL. If hosted account management is disabled, this URL will 404.
  • {{account_has_coupon?}}
    Returns true is this account has an active coupon.
  • {{coupons}}
    Returns coupon information if this account has active coupons.
  • {{account_vat_number}}
    The Account Info VAT Number is relevant for customers being issued a manual invoice or if you have your Tax Settings set to have invoices use the Account Info address on the invoice.

Coupon Fields

  • {{coupon_code}}
  • {{coupon_name}}
  • {{coupon_lifetime}}
    A string of either: Forever, Single use, or #months
  • {{coupon_discount_percent?}}
    Returns true is this coupon is a percent off discount
  • {{coupon_discount_amount?}}
    Returns true is this coupon is an amount off discount
  • {{coupon_discount_percent}}
  • {{coupon_discount_amount}}
  • {{coupon_description}}

Billing Info Fields

  • {{billing_cc_type}}
    Credit card type, e.g. Visa, MasterCard, etc. Will not return anything if payment was made through PayPal.
  • {{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_applicable?}}
    Returns true if the account charges VAT.
  • {{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 curly 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.
  • {{invoice_po_number}}
    Indicates invoice PO Number for manual invoicing.
  • {{invoice_net_terms}}
    Indicates invoice net terms for manual invoicing.
  • {{invoice_has_tax?}}
    Returns true if the invoice has taxes applied.
  • {{invoice_tax_amount}}
    Total amount of the taxes applied to the invoice.
  • {{invoice_tax_rate}}
    Percentage tax rate that was applied to the invoice, e.g. "7.25%".
  • {{invoice_tax_region}}
    The region for which the taxes were collected, e.g. "CA" or "DE".
  • {{invoice_customer_notes}}
    Any notes that were in the Customer Notes field on the invoice.
  • {{invoice_terms_and_conditions}}
    Any notes that were in the Terms and Conditions field on the invoice.
  • {{invoice_vat_reverse_charge_notes}}
    Any notes that were in the VAT Reverse Charge Notes field on the invoice. This field is only relevant to EU VAT Reverse Charge scenarios.

Line item fields

  • {{{line_date}}}
    Requires 3 curly braces. Line item date or date range.
  • {{line_description}}
  • {{{line_amount}}}
    Requires curly braces Line item total amount.
    {{line_amount_is_zero?}}
    Returns true if the line item has a 0 amount.
  • {{{line_unit_amount}}}
    Requires 3 curly braces. Line item unit amount.
  • {{{line_quantity}}}
    Requires 3 curly braces. Line item quantity.
  • {{line_quantity_is_one?}}
    Returns true if the line item quantity is 1.
  • {{line_accounting_code}}
    Accounting code of the line item's charge.
  • {{line_discount_amount}}
    Returns the line item's discount amount, if one exists. Otherwise, it returns 0. Purchase discounts will return as a positive value. Refund discounts will return as a negative value. Wrap this parameter in the invoice_has_discount check to only show your display if at least one of the line items has a discount. Note that this email parameter is not included in any of the email templates by default, so you will need to edit the template to include the parameter.

Subscription and Add-on Fields

  • {{subscription_active?}}
    Returns true if the subscription is currently active.
  • {{subscription_quantity}}
    Subscription quantity.
  • {{subscription_quantity_is_one?}}
    Returns true if the subscription's quantity is one.
  • {{{subscription_total_amount}}}
    Requires 3 curly braces. 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_trial_without_billing_information?}}
    Returns true if the billing info is empty and reason is no_billing_info_reason? = plan_free_trial. This is useful for Trial Ending emails for free trial subscriptions that don't require billing information to show special messaging about adding a payment method.
  • {{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 subscription billing period ends, including trial periods.
  • {{subscription_current_period_ends_at_with_time}}
    Date and time (UTC) when the current subscription billing period ends, including trial periods.
  • {{subscription_next_payment_date}}
    Date when the next payment will be charged.
  • {{subscription_add_ons}}
    Will list any add-ons in the subscription.
  • {{add_on_name}}
    If included in the subscriptions_add_ons block, it will return the name of the add-on.
  • {{add_on_price}}
    If included in the subscriptions_add_ons block, it will return the price of the add-on. If the add-on is usage-based and the percentage of an amount pricing model, this parameter will return a percentage.
  • {{add_on_usage_based?}}
    Returns true if the add-on is usage-based. If included in the subscriptions_add_ons block, it will allow you to isolate usage-based add-ons in order to provide a different pricing display.
  • {{add_on_percentage?}}
    Returns true if the add-on is usage-based and has the percentage of an amount pricing model. If included in the subscriptions_add_ons block, it will allow you to isolate usage-based add-ons that display a percentage for the {{add_on_price}} parameter.
  • {{add_on_measured_unit_display_name}}
    If included in the subscriptions_add_ons block and the add-on is usage-based, this will return the associated measured unit display name.

Gift Card fields

  • {{gift_card_redemption_code}}
    The current redemption code of the gift card.
  • {{gift_card_amount}}
    The amount of the gift card.
  • {{gift_card_currency}}
    The currency of the gift card amount.
  • {{gift_card_delivery_first_name}
    The first name of the gift recipient.
  • {{gift_card_delivery_last_name}
    The last name of the gift recipient.
  • {{gift_card_personal_message}}
    The personal message for the gift recipient.
  • {{gift_card_gifter_name}}
    The gifter's name specified for the delivery messaging.
  • {{{gift_card_image}}}
    The current gift card product's image.
  • {{gift_card_delivery_method}}
    Whether the gift card has a delivery method of email or post.
  • {{gift_card_delivery_email_address}}
    The gift card recipient's email address.
  • {{gift_card_delivery_address1}}
    The gift card recipient's address1.
  • {{gift_card_delivery_address2}}
    The gift card recipient's address2.
  • {{gift_card_delivery_city}}
    The gift card recipient's city.
  • {{gift_card_delivery_state}}
    The gift card recipient's state.
  • {{gift_card_delivery_zip}}
    The gift card recipient's zip.
  • {{gift_card_delivery_country}}
    The gift card recipient's country.
  • {{gift_card_delivery_phone}}
    The gift card recipient's phone.
  • {{gift_card_delivery_deliver_at}}
    The future delivery date of the gift card.
  • {{#gift_card_has_personal_message?}}
    If the gift card has a value in the personal message field. Useful for hiding the personal message display if one was not included at purchase.
  • {{#gift_card_has_gifter_name?}}
    If the gift card has a value in the gifter name field. Useful for hiding the gifter name display if one was not included at purchase.
  • {{#gift_card_has_image?}}
    If the gift card product has an image currently uploaded. Useful for hiding the image display if the gift card product does not have an image.
  • {{#gift_card_has_deliver_at?}}
    If the gift card has a future delivery date.
  • {{#gift_card_delivery_city?}}
    If the gift card has a city in the delivery address. Useful for hiding an address comma after the city if there is no city in the address.
  • {{#subscription_is_gift?}}
    If the subscription started with a gift card. Useful with account_has_billing_info? below in subscription emails to show special messaging to gift card customers about adding a payment method.
  • {{^account_has_billing_info?}}
    If the billing information on the account doesn't exist. Useful nested under subscription_is_gift? in subscription emails to show special messaging to gift card customers about adding a payment method.

Transaction fields

  • {{transaction_id}}
    Transaction's UUID: 32-characters, alphanumeric.
  • {{transaction_amount}}
    Transaction dollar amount.
  • {{transaction_status}}
    Transaction status (success/void/decline).
  • {{transaction_date}}
    Transaction date.
  • {{#transaction_ach?}}
    Returns true if the transaction was paid via ACH.

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. Click the Customize button associated with the appropriate email template
  2. Click the Edit button in the “Plain-text Body” or “HTML Body” section
  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.

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 and it is in ours and your best interest to ensure that these emails are received by their intended recipients. Recurly offers best-in-class email deliverability rates.

SPF and DKIM Email Signing

Recurly offers both SPF and DKIM signing of emails. When you configure your email templates and send from email address, Recurly will sign emails using SPF and DKIM, which provide better email deliverability. These emails will be signed by Recurly.com.

DMARC Email Signing

We currently do not offer DMARC signing on emails sent through Recurly.

Coming Soon!

We are soon releasing a new email template experience. This functionality will include a new UI, as well as the ability to send a test email to yourself to see what each email will look like. Please stay tuned for these changes to make their way into a future release!

Email Templates

From invoice receipts to declined payments, Recurly can email your subscribers on your behalf. The emails can be customized and individually enabled.