====== Email Receipts ======
===== What's In an Email Receipt? =====
{{ :v:2.0:email_receipt.png?direct&200|An example email receipt sent by FoxyCart using the default HTML Responsive template}}

FoxyCart's email receipts include almost everything in [[.:receipt#what_s_included_on_the_receipt|the web receipt]], as well as any additional text you have configured in your receipt template(s). (You can see an example receipt to the right.) The major difference between the web receipt and the email receipts is that email receipts have specific sections that are only included in certain situations. 

Email receipts for each transaction are sent to the customer by default. You can turn this off by going to the [[https://admin.foxycart.com/admin.php?ThisAction=EditTemplate&template=email|email receipt]] settings of the Foxy admin and removing the text from the **receipt email subject** setting. The email receipt will also not be sent to the store in this case.

==== Transaction Email Receipts ====
A "transaction email receipt" is what you'd probably consider to be a "normal" receipt. It's the main content section of a typical receipt, and will generally include the cart contents and transaction information (customer name, email, address, shipping info, etc.).

Important to note is that the default template will include a block of text (customizable in your store's [[.:i18n|language section]]) with subscription-specific links //if// a subscription is present in the cart. By default, these links will allow your customers to update their payment information or cancel their subscriptions straight from the email receipts they're already receiving. If you're doing [[.:products:subscriptions|recurring billing]] through FoxyCart we strongly recommend taking a look at that text, and running a few test orders.

The transaction email receipt will include everything that's part of [[.:receipt|the web-based receipt]] that is displayed to the customer after a successful transaction (in their web browser).

==== Subscription Cancellation Confirmation Email Receipts ====
Breaking up is hard to do, so FoxyCart allows for a customizable section to be included if (and only if) the email receipt is for a subscription cancellation. This will help you make it clear to the customer that their subscription has been set to cancel. These are sent only after a subscription has been successfully canceled //[[.:checkout#subscription_cancellation|through the checkout process]]//. <wrap important>These emails will //not// send if a subscription is set to end or set to be inactive via the administration or [[.:api|the API]].</wrap>

==== "Update Info" Email Receipts ====
When a customer [[.:checkout#update_info_requests|updates their information with the ''updateinfo'' flag]], this section is included in the email receipt.

===== Who Gets Email Receipts? =====
**The customer.** If you have a "receipt email subject" configured in your store's "email" section, the customer will receive an email receipt for any transaction run on their account, including every time their account is billed for any recurring billing they have.

**The store.** If you have the "BCC store email address" checkbox checked in your store's "email" section, the store email address (as configured in your store settings) will receive a BCC copy of the email address. <wrap important>Note that this is a straight BCC copy,</wrap> and looks //identical// to the customer's email receipt. If you're testing with an email address that goes to the same place as the store's email, you likely will only see //one// email receipt, since many mail servers would discard the extra copy as a duplicate. 

**Other addresses.** <wrap tip>If you'd like to send receipts to more than one person</wrap> at your organization, just add additional emails to the "store email(s)" field in the "store settings" page in the admin. Separate emails by commas. You can also see the [[#category_specific_email_receipts|category specific email receipts]] section below for info on sending to other email addresses.

===== Default Templates and Customizations =====
The default HTML email receipt template is visible above at the right, but you can fully customize your email receipt much like you'd do with any other template on your store. If you're just looking to change language (such as the message that appears at the top or labels for sections) we'd suggest you start with making changes in the strings in the [[https://admin.foxycart.com/admin.php?ThisAction=Internationalization|language section of your store's Foxy administration]].

If you choose to [[v:2.0:templates|alter the base templates]] in the //email receipt// settings, the big difference is that email formatting is stuck in the 1990s, so you'll want to brush up on HTML email formatting. [[http://www.campaignmonitor.com/|CampaignMonitor]] has //fantastic// templates and [[http://www.campaignmonitor.com/css/|resources for CSS support in HTML emails]] that we highly recommend.

As the Foxy email receipt templates handle a number of different emails beyond the normal transaction email receipt (including subscription reminders and cancellations), and the default styles are inlined in the HTML, it does make the template a bit more complex to customise. We know that can make them a bit imposing to work with, and are considering options of email editors that could potentially be integrated.

Here's some general tips for customising the email receipts beyond just language customisations:
  * We would recommend copying the HTML template out into a text editor for modification. One with syntax highlighting (and optionally with support for Twig template language) will make the template easier to work with.
  * If you're looking to use a completely different template from another service, you'll need to bring in the Twig logic to handle the different email types and outputting the customers information. There's [[#email_receipt_placeholders|also an overview at the bottom of this page]] with all the placeholders available to the email receipt.
  * If you need to reference the default HTML template at all, [[https://github.com/FoxyCart/2.0-templates/blob/master/default_templates/responsive.email.twig|that's also available on Github here]].
===== Category Specific Email Receipts =====
FoxyCart allows additional emails to be configured //per [[.:categories|category]]//. The first option is to enable an additional customer email, which could be useful if a specific product category required extra information like conference registration information, special shipping or pickup information, or a request for additional information. The second option is for an additional admin email to be sent, which could be useful if sales of certain products need to notify specific departments within an organization.

You can add category emails in your categories [[https://admin.foxycart.com/admin.php?ThisAction=ManageProductCategories#fs_category_email|here]].


===== When Email Receipts are Sent =====
Email receipts are sent only in the following two situations:
  - A customer places a //successful// order.
  - A store administrator manually resends the email receipt from the "transactions" page in the store's admin.

===== Didn't Get an Email Receipt? =====
If you didn't receive an email receipt that you think you should have, please follow the steps below to ensure we've ruled out the common causes before you contact support.
  - Check your spam folder. Though we have exceedingly high deliverability rates, and only send from clean IP addresses, it can happen.
  - Reread the [[#who_gets_email_receipts|"Who Gets Email Receipts"]] section above, and double confirm that your customer email receipt isn't going to the same place as your store's BCC copy.
  - Be sure that the email address actually exists and can accept mail. Quite often when we look into our mail logs we find that a mail server hasn't been set up or that the email address in question doesn't exist.
  - [[mailto:helpdesk+email@foxycart.com|Contact support]], being sure to include the exact email address that isn't receiving emails.


===== How Emails Are Sent (SPF, DKIM, DMARC, etc.) =====

There are 3 ways Foxy can be configured to send emails on your store's behalf:
  - **Default:** The email's ''From'' address is your store's configured email, but Foxy's address is the ''Return-Path'' (meaning we get the bounces), and we'll add a ''Sender'' header, so some mail clients may show a message that your email receipts are "on behalf of" or "sent via". SPF and DKIM pass, but **//DMARC will fail//**. If you use DMARC on your domain, you'll need to do one of the following.
  - **Email DNS:** This approach requires some DNS records to be added to your domain, and will allow us to avoid the "sender" header mentioned above. SPF and DKIM pass, and DMARC should pass.
  - **Bring Your Own SMTP:** You can also configure your own SMTP server, and Foxy will simply use that. You're responsible for SPF, DKIM, and DMARC, but you may have more control and visibility (if you're using something like MailChimp Mandrill, Zoho ZeptoMail, PostmarkApp, etc.). Note that if there's a connection error, Foxy will fall back to the "default" option above.

More details about these options are below

==== Using FoxyCart's Mail Servers (Default) ====

By default, FoxyCart sends emails with extremely high deliverability rates, passing both SPF and DKIM standards. Though your configured email address will be in the ''From'' line of the email, we //do use an @foxycart.com address// in the ''Sender'' header, which can cause some mail clients (like Outlook and Hotmail) to display an "on behalf of" message when viewing the message details. Google does something similar by adding a "via" heading.

This default option is easy, reliable, and requires no additional work from you. But if you don't want the "on behalf of" or "via" text, //OR// if you're using DMARC, you must use one of the following options.

Some domains like ''@yahoo.com'' have strict DMARC policies, which prevent us from spoofing their emails. If you set your store email address to these domains (including ''aol.com'', ''gmail.com'', ''googlemail.com'', ''hotmail.com'', ''live.com'', ''outlook.com'', ''verizon.net'', ''yahoo.ca'', ''yahoo.com''), we cannot use your configured email address as the ''From'' address, so we will send from a Foxy address, with your store's email as the ''Reply-To''. This isn't great, so we recommend using an email at your own domain if you can.

==== Foxy's "Email DNS" Functionality ====

SPF and DKIM both use the ''Return-Path'' address (aka "mail from", "bounce address", "envelope header") to validate, which is generally invisible to the recipient, which means an email could pass SPF and DKIM but the ''From'' address could be completely different. DMARC fixes this by relying on SPF or DKIM passing with a ''Return-Path'' address that matches the domain of the ''From'' address.

In order for Foxy to send email on your behalf using your domain in the envelope header, you'll need to add a few DNS records. Note also that in this situation we'll remove the ''Sender'' header, so there will be no "on behalf of" text in any clients. Our mail servers still handle everything for you, but without any Foxy-related email addresses showing anywhere.

To enable this, go to your "advanced" section in your [[https://admin.foxycart.com/|FoxyCart admin]] and enable the "enable email DNS" checkbox. It may take a few hours after your DNS is updated for this to be enabled. You can contact support if you'd like a status update.

^ Record Type       ^ Subdomain           ^ Value                                         ^
| TXT                | ''smtpapi._domainkey''     | <code>
k=rsa; t=s; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDPtW5iwpXVPiH5FzJ7Nrl8USzuY9zqqzjE0D1r04xDN6qwziDnmgcFNNfMewVKN2D1O+2J9N14hRprzByFwfQW76yojh54Xu3uSbQ3JP0A7k8o8GutRF8zbFUA8n0ZH2y0cIEjMliXY4W4LwPA7m4q0ObmvSjhd63O9d8z1XkUBwIDAQAB
</code>  |
| TXT               | ''@''     | Add ''include:_spf.foxycart.com'' to your existing SPF record.       |

If you don't already have an SPF record on your domain, you will need to create one. While the details of creating an SPF record go beyond what we can provide here, you can generally pretty easily ask your web host for help, or Google for records to use. For example:
  * [[http://www.google.com/support/a/bin/answer.py?answer=178723|Help from Google Apps]], if you use Google Apps for your mail
  * [[https://www.spf-record.com/generator|spf-record.com/generator]], which may be very useful. In the second step, expand the "Advanced Settings" section and add ''_spf.foxycart.com'' in the "Delegate to external SPF record (include)" text area. Note the value for your SPF record will be the portion in the text input that they generate, beginning with ''v=spf1''.


==== Using Your Own SMTP Server ====

If you'd like, you can configure FoxyCart to send email using your own SMTP credentials. You can enable it from the "advanced" settings page of your [[https://admin.foxycart.com/|FoxyCart admin]], within the "Email Receipt Settings" section labelled "Use your own smtp server". A few things to note, if you go this route:

  * If our servers cannot make a connection to your SMTP server, we will failover to our normal email handling, as described in the section above. For that reason…
  * We recommend you configure the "email DNS", so if/when FoxyCart does send mail on your behalf, it's a slightly more similar approach (and avoids the "via email.foxycart.com" language).


===== Email Receipt Placeholders =====
Customizing the email receipts is much like customizing any other template, but there are a few email-specific values that can be customized to change the email behavior. These values should be set under the "email receipt" settings in the //**receipt text email template**//, at the top of the text area. This applies whether or not you're using the HTML version. You may need to select the "Custom Text Template" option to get this text box to appear.

Note that the Twig variables available in the "receipt email subject:" setting are very limited, and so if you need to access a variable such as the customer's first name, you'll need to make the customization within the "receipt text email template:" text area rather than the "receipt email subject:" field.

Here are some email-specific values that can be customized:   
  * ''email_subject'': Can be used to //set// the email subject. If set to an empty string, the email will not be sent.
  * ''email_from'': Can be used to //set// the email's ''from'' header.
  * ''email_replyto'': Can be used to //set// the email's ''reply-to'' header.
  * ''email_bcc'': Can be used to //set// the email's ''bcc'' addresses, comma separated. So if you want to BCC an address conditionally (based on country, cart contents, whatever), you can. The "bcc store email address" option needs to be enabled in your email settings to customise, and whatever it is set to in Twig will overwrite the store emails it would normally BCC to.


You'd set these using Twig and a custom ''fc_output_data'' filter, like this:
<code twig>
{% set custom_subject = 'custom email subject for order ' ~ order_id ~ ' shipping to ' ~ shipping_address.first_name %}
{{ custom_subject|fc_output_data('email_subject') }}

{% set custom_from = 'someone@example.com' %}
{{ custom_from|fc_output_data('email_from') }}

{% set custom_bcc = 'someone_else@example.com' %}
{{ custom_bcc|fc_output_data('email_bcc') }}
</code>


==== Full List of All Placeholders ====
{{section>.:cheat_sheet#view_data&noheader&noeditbutton&permalink&footer&nodate}}