# Write the emails your store sends

> Change the subject and the words of each email the store sends its shoppers, preview it with sample data, send yourself a test and go back to the default.

Source: https://www.coritan.com/docs/organizations/commerce/emails/

In the dashboard:

- /dashboard/organizations/…/commerce/emails: https://www.coritan.com/dashboard/organizations

**Emails** lists every email the store sends its shoppers. Each one sends Coritan's default until you save your own version. You can change its subject, its HTML and its plain text, see it rendered with sample data, send yourself a test, and go back to the default at any time.

## Before you begin

- You need the Admin or Owner role to change an email, send a test or turn the shipping notice on or off. Every member can open **Emails**, read each template and see its preview.
- The emails go out in your organization's email design, with its logo, colours and footer. You change those under the organization's email settings, not here.

## The emails

The list names each email and says whether it sends **Your version** or the **Default**. Emails marked **Marketing** are sent by the store's [flows](/docs/organizations/commerce/marketing/), such as the abandoned cart reminders. They carry an unsubscribe link and never go to an address that unsubscribed or that you added to the suppression list. The others go to every shopper the order concerns.

| Email | When it is sent |
| --- | --- |
| Order confirmation | When an order is placed: what was ordered, the totals and the link to the order. |
| Order shipped | When a parcel leaves: the items in it, the carrier, the tracking number and the tracking link. A split shipment sends one email for each parcel. |
| Order cancelled | When the store cancels an order, with what was refunded. |
| Refund issued | When part or all of an order is refunded. |
| Gift card | To the recipient of each gift card an order sold, with its code. |
| Order lookup | When a shopper asks for links to the orders placed with their address. |
| Set your password | To a shopper whose account needs a password, with the link that sets one. |

A test order's emails go out too, with `[TEST]` in front of the subject.

## Turn the shipping email on or off

At the top of **Emails**, **Email the shopper when a parcel ships** is on for a new store. Turn it off if your fulfilment provider already emails your shoppers with tracking, so they do not get two. While it is off, no shipping email goes out, and the shopper can still follow the order from its page.

## Change an email

1. Open **Emails** and choose the email.
2. Change the **Subject**, the **HTML** or the **Plain text**. The preview follows a moment after you stop typing.
3. Choose **Save changes**. The next email of that kind uses your version.

The HTML goes inside the organization's email layout, so write only the body: paragraphs, links and buttons. The plain text is what mail apps that show no HTML display. You need a subject and at least one of the two bodies.

When a field cannot be used, Save refuses it and says which field and which line, under that field. Nothing is saved until every field works.

### Variables

A variable puts a value from the order into the email. Write its name in double braces: `{{ order_number }}` becomes `#1042`. The editor lists each variable the email is given, with what it holds. You can also choose between words with `{% if %}` and list items with `{% for %}`, for example:

```
{% for item in items %}{{ item.quantity }} x {{ item.title }}
{% endfor %}
```

Every order email is given these:

| Variable | What it holds |
| --- | --- |
| `customer_name` | The shopper's first name, or "there" when the order has none. |
| `store_name` | The store's name. |
| `order_number` | The order's number, such as #1042. |
| `order_url` | The link to the order on the storefront, which opens without signing in. The gift card email does not have it. |
| `invoice_number` | The number of the order's invoice, when it has one. |
| `seller_legal_name` | The Coritan company that sold the order on behalf of the store. |
| `currency` | The order's currency code, such as EUR. |
| `support_email` | The store's support address, when it has one. |
| `subject_prefix` | `[TEST] ` on a test order, and nothing on a live one. |
| `is_test` | True on a test order. |

The shipping email is also given these:

| Variable | What it holds |
| --- | --- |
| `items` | The items in this parcel, each with `title` and `quantity`. |
| `carrier` | The carrier of the first tracking number, such as DHL. |
| `tracking_number` | The first tracking number. |
| `tracking_url` | The link to follow the first tracking number, when the carrier gave one. |
| `tracking` | Every tracking number of the parcel, each with `carrier`, `number` and `url`. |
| `shipping_address` | The address the parcel goes to, on one line. |
| `shipping_name` | The shipping method's name. |
| `partial` | True when more of the order ships later. |

The editor lists the variables of the other emails: the totals of the order confirmation, the amounts of a refund, the code of a gift card, the orders of an order lookup and the link of a password email.

### What a template can do

Templates run in a sandbox on Coritan's servers. A template can read the variables listed for it and use `if`, `for` and filters such as `upper`. It cannot reach anything else: not the server, not other organizations' data, and not Python's internals. A template that tries is refused when you save it.

The sandbox also refuses a template that would build something huge, such as a word repeated a billion times.

If a saved template fails when a real email goes out, for example because a variable holds something you did not expect, Coritan sends the default for that email instead, so the shopper still gets it. The failure is logged for Coritan's staff with the email's name, never with your text.

## Preview an email

The preview on each email's page shows it as a shopper would get it, in the organization's layout, with sample data: an order #1042 from your store to a shopper called Alex. The preview runs no scripts, and its links point at sample addresses.

## Send yourself a test

Choose **Send a test to me** on an email's page. The test goes to your own address, the one you sign in with, and to no one else. It is the saved version with sample data, and its subject starts with `[Test]`. Save your changes first if you want to test them.

You can send ten tests an hour. After that, the page says to try again later.

## Go back to the default

Choose **Reset to default** on an email you changed, and type the email's name to confirm. Your version is deleted, and the store sends Coritan's default from then on. This cannot be undone, so copy your text somewhere first if you may want it again.

## Related

- [Orders](/docs/organizations/commerce/orders/): shipping a parcel, which sends the shipping email.
- [Fulfilment providers](/docs/organizations/commerce/fulfilment-providers/): a provider that reports a parcel as shipped sends it too.
- [Settings](/docs/organizations/commerce/settings/): the store's name and support address the emails use.

## API

- `GET /api/v1/orgs/{org_slug}/commerce/email-templates`: List templates (https://www.coritan.com/docs/api/reference/organizations/commerce/commerce/#op-get-api-v1-orgs-org-slug-commerce-email-templates)
- `GET /api/v1/orgs/{org_slug}/commerce/email-templates/{slug}`: Get template (https://www.coritan.com/docs/api/reference/organizations/commerce/commerce/#op-get-api-v1-orgs-org-slug-commerce-email-templates-slug)
- `PUT /api/v1/orgs/{org_slug}/commerce/email-templates/{slug}`: Save the store's own version of a template: {subject, html, text} (https://www.coritan.com/docs/api/reference/organizations/commerce/commerce/#op-put-api-v1-orgs-org-slug-commerce-email-templates-slug)
- `DELETE /api/v1/orgs/{org_slug}/commerce/email-templates/{slug}`: Go back to the platform's default: the store's own version is deleted (https://www.coritan.com/docs/api/reference/organizations/commerce/commerce/#op-delete-api-v1-orgs-org-slug-commerce-email-templates-slug)
- `POST /api/v1/orgs/{org_slug}/commerce/email-templates/{slug}/preview`: Preview template (https://www.coritan.com/docs/api/reference/organizations/commerce/commerce/#op-post-api-v1-orgs-org-slug-commerce-email-templates-slug-preview)
- `POST /api/v1/orgs/{org_slug}/commerce/email-templates/{slug}/test`: Send test (https://www.coritan.com/docs/api/reference/organizations/commerce/commerce/#op-post-api-v1-orgs-org-slug-commerce-email-templates-slug-test)