# Email Templates

Templates are at the core of Finqu emails. Each email sent by Finqu has a corresponding template file, following a clear and consistent naming convention. Templates define the content, subject, and structure of the emails your customers receive.

---

## Contexts

Templates are organized by context, which determines the available variables and the purpose of the email. The main contexts are:

### customers
Emails sent to customer accounts.

**Global variables:**
| Variable  | Description                                              |
|-----------|----------------------------------------------------------|
| customer  | The customer account object.                             |
| channel   | The sales channel from which the email was sent.         |

**Subject line variables:**
| Variable    | Description                        |
|-------------|------------------------------------|
| FIRST_NAME  | Customer's first name              |
| LAST_NAME   | Customer's last name               |
| NAME        | Customer's full name               |

### orders
Emails sent in the context of an order.

**Global variables:**
| Variable  | Description                                              |
|-----------|----------------------------------------------------------|
| customer  | The customer account object.                             |
| channel   | The sales channel from which the email was sent.         |
| order     | Information about the order.                             |

**Subject line variables:**
| Variable     | Description                              |
|--------------|------------------------------------------|
| FIRST_NAME   | Customer's first name                    |
| LAST_NAME    | Customer's last name                     |
| NAME         | Customer's full name                     |
| ORDER_ID     | Unique ID of the order                   |
| ORDER_NUMBER | Merchant's order number for this order   |

---

## Available Templates

Some templates provide special variables for action links or detailed context. These are listed in the last column.

| Template file                        | Description                                              | Special variables                |
|--------------------------------------|----------------------------------------------------------|----------------------------------|
| customers/recover_password.mjml.liquid | Password recovery email                                  | link_to_recovery                 |
| customers/register.mjml.liquid         | Welcome email for new customers                          |                                  |
| orders/confirmation.mjml.liquid        | Order confirmation                                       | link_to_order                    |
| orders/fulfillment.mjml.liquid         | Order fulfillment notification                           | shipment                         |
| orders/gift_card.mjml.liquid           | Gift card information                                    | gift_card (value, code, expiry)  |
| orders/message.mjml.liquid             | Order message or information                             | shipment, message                |
| orders/payment_link.mjml.liquid        | Payment link for completing purchase                     | link_to_checkout                 |
| orders/return.mjml.liquid              | Return confirmation                                      | return                           |
| orders/status.mjml.liquid              | Order status update                                      | link_to_order                    |

---

## Template File Structure

A template file consists of three main components:

1. **HTML (MJML)**: The main content of the email, written in [MJML](https://mjml.io/) and Liquid. All content outside `plaintext` and `schema` tags is rendered as HTML.
2. **Plaintext**: (Optional but recommended) A simple text version of your email, wrapped in `plaintext` tags. This ensures compatibility with all email clients.
3. **Schema**: Defines the subject and preview text for the email, wrapped in `schema` tags. You can use subject line variables here.

### Example Structure

```liquid
<mj-section>
  <mj-column>
    <mj-text>Hello {{ customer.first_name }}!</mj-text>
  </mj-column>
</mj-section>

{% plaintext %}
Hello {{ customer.first_name }}!
{% endplaintext %}

{% schema %}
{
  "subject": "Hi ${FIRST_NAME}, your order is confirmed!",
  "preview": "Order confirmation for ${FIRST_NAME}."
}
{% endschema %}
```

#### About `subject` and `preview` in Schema

- **subject**: Defines the subject line of the email. You can use subject line variables (e.g., `${FIRST_NAME}`, `${ORDER_NUMBER}`) to personalize the subject for each recipient. The subject can be a string or an object for localization.
  - Example: `"subject": "Hi ${FIRST_NAME}, your order is confirmed!"`
  - Localized example:
    ```json
    {
      "subject": {
        "en": "Hi ${FIRST_NAME}!",
        "fi": "Hei ${FIRST_NAME}!"
      }
    }
    ```
- **preview**: Sets the preview text (sometimes called preheader) that appears in many email clients after the subject. This gives recipients a short summary of the email content. Like `subject`, you can use variables and localize the value.
  - Example: `"preview": "Order confirmation for ${FIRST_NAME}."`
  - Localized example:
    ```json
    {
      "preview": {
        "en": "Order confirmation for ${FIRST_NAME}.",
        "fi": "Tilausvahvistus ${FIRST_NAME}:lle."
      }
    }
    ```

Both properties support all subject line variables available for the template context. If a localized value is not found for the recipient's language, the default (usually English) is used.

---

## Best Practices
- Always provide a plaintext version for maximum compatibility.
- Use MJML for responsive and robust HTML emails.
- Leverage available variables and special variables for dynamic content.
- Localize schema fields for multilingual support.
- Keep template names and structure consistent for maintainability.

---

For more details on available variables and objects, see the reference documentation for [Objects - Email](https://developers.finqu.com/docs/reference/theme/objects/email) and [Objects - Store](https://developers.finqu.com/docs/reference/theme/objects/store).