> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Emails

> Which emails the shop sends, how sender, subject, and template are configured per email, how PDF attachments and SEPA mandates are created, and how sending via an external mail system works.

A WEBSALE shop sends around twenty different emails. Each one has its own section in the `shop.config`, and almost all of them follow the same blueprint of sender, subject, and template.

That's why this page starts with exactly this common blueprint and with sending via an external mail system, which applies to almost all sections. After that, the emails follow in the order in which they occur in a customer's lifecycle. First registration, then the order, then follow-up actions, and finally newsletters, freely definable emails, and notifications to the administrator.

Reference: Shop configuration shop.config, overview of all sections

## The common blueprint

Most email sections share the same four to five parameters.

| Parameter | Purpose |
| - | - |
| `Allow` | Activate the email. `yes` or `no`, default `no` |
| `Subject-Txt` | Subject |
| `SenderAddress` | Sender address |
| `SenderName` | Sender name |
| `Template` | HTML template of the email |

The following sections only list what differs from this blueprint.

> [!NOTE]
>
> Not every section has an `Allow`. The emails for the double opt-in procedure, the password, and the product recommendation are triggered by the respective function, not by a separate switch.

## Sending via an external mail system

Many sections can hand off sending to an external mail system. Inxmail Commerce is currently supported.

| Parameter | Purpose | Values |
| - | - | - |
| `UseExternMailSystem` | which mail system sends | `no`, `InxMail`, `InxMail_test`. Default: `no` |
| `ExternMailTemplate` | Template for the external system | File name, for example `customer_mail.inxmail` |

`no` uses the WEBSALE standard email. `InxMail` hands off sending to Inxmail and uses the template from `ExternMailTemplate` for it. `InxMail_test` does the same, but only in the shop's test mode. In live operation, the standard email applies again.

> [!WARNING]
>
> If `ExternMailTemplate` remains empty, the kernel silently disables the external mail system and sends via the WEBSALE standard email. No error message appears.
>
> The same happens with a typo in `UseExternMailSystem`. Any value that doesn't name a known mail system acts like `no`.
>
> Neither is described in the previous documentation; both are added here. So after a switchover, always check whether emails are actually being sent via the external system.

Guide: Sending shop emails via Inxmail Commerce

## Registration and customer account

### `RegistrationMail`

Welcome email after the first registration in the shop. Supports the common blueprint including `Allow`, as well as `UseExternMailSystem` and `ExternMailTemplate`.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<RegistrationMail>
   Allow         = yes
   Subject-Txt   = Willkommen in unserem Shop
   SenderAddress = shop@mein-shop.de
   SenderName    = Mein Shop
   Template      = mail_registration.htm
</RegistrationMail>
```

### `NewCustomerMail`

Email to new customers. Supports the common blueprint including `Allow`, but **no** external mail system.

### `NewCustomerDoubleOptInMail`

Confirmation email during new customer sign-up when the double opt-in procedure with **mandatory** confirmation of the email address is active. Supports the common blueprint without `Allow`, plus `UseExternMailSystem` and `ExternMailTemplate`.

### `CustomerVoluntaryDoubleOptInMail`

The same for the **voluntary** confirmation of the email address. Same parameters.

### `ChangeEmailDoubleOptInMail`

Confirmation email when changing the email address in the customer account. Same parameters.

### `DeleteAccountDoubleOptInMail`

Confirmation email for the "Delete customer account" function. Same parameters.

### `SetPasswordMail`

Email of the "Forgot password" or "Reset password" function. Supports the common blueprint without `Allow`, plus `UseExternMailSystem` and `ExternMailTemplate`.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<SetPasswordMail>
   Subject-Txt   = Ihr neues Passwort
   SenderAddress = shop@mein-shop.de
   SenderName    = Mein Shop
   Template      = mail_set_password.htm
   RateLimit     = 5
</SetPasswordMail>
```

| Parameter | Purpose | Values |
| - | - | - |
| `RateLimit` | how many password emails are allowed per time period | Number from 1. Default: 5 |

> [!NOTE]
>
> `RateLimit` isn't described in the previous documentation and is added here. Values below 1 are silently set to 5.
>
> In the sample code of the source documentation, a stray `b` appeared after `UseExternMailSystem`. It has been removed here.

## Order

### `CustomerMail`

The order confirmation to the buyer. This is the most extensive email section, because the PDF attachments and SEPA mandates are also configured here.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<CustomerMail>
   Allow           = yes
   Subject-Txt     = Ihre Bestellung bei Mein Shop
   SenderAddress   = shop@mein-shop.de
   SenderName      = Mein Shop
   Template        = mail_customer_order.htm
   AttachPDF-Allow = yes
   PDFTemplate     = pdf_order.htm
   PDFFileName     = Bestellung_~WS-OrderID~.pdf
   <+Attachment>
      Name = AGB.pdf
      File = deutsch/pdfs/agb.pdf
   </+Attachment>
</CustomerMail>
```

#### Order details as PDF attachment

| Parameter | Purpose | Values |
| - | - | - |
| `AttachPDF-Allow` | Attach order details as PDF | `yes`, `no` |
| `PDFTemplate` | HTML template that is converted to the PDF | Template name |
| `PDFFileName` | File name of the attachment. Supports the `WS-OrderID` tag | for example `Bestellung_~WS-OrderID~.pdf` |

#### Additional file attachments

Up to five `+Attachment` subsections attach fixed files, for example terms and conditions or the cancellation policy.

| Parameter | Purpose |
| - | - |
| `File` | File to attach, relative to the template directory |
| `Name` | Optional file name under which the attachment reaches the buyer |

If `Name` is missing, the file name is derived from `File`. `deutsch/12345.pdf` then becomes the attachment `12345.pdf`.

> [!WARNING]
>
> The path in `File` must be specified **relative to the template directory**. If the file is located at `/benutzer/templates/deutsch/pdfs/agb.pdf`, the value is `deutsch/pdfs/agb.pdf`.
>
> Paths that lead out of the template directory are checked by the kernel, and the attachment is silently discarded. No error message appears; the email goes out without this attachment. This check isn't documented and is added here.

> [!NOTE]
>
> A purchase voucher can't be sent as a PDF attachment. It's only available via a download link, either in the order confirmation or in the order history of the customer account.

#### SEPA mandates

| Parameter | Purpose | Default |
| - | - | - |
| `SEPACustomerPDFTemplate` | Template of the mandate for the SEPA Core Direct Debit | `pdf_sepa_customer.htm` |
| `SEPACustomerPDFFileName` | File name of this mandate | see note below |
| `SEPACompanyPDFTemplate` | Template of the mandate for the SEPA Business-to-Business Direct Debit | `pdf_sepa_company.htm` |
| `SEPACompanyPDFFileName` | File name of this mandate | see note below |

> [!WARNING]
>
> If you leave all four parameters empty, **no mandate numbers are generated and no PDF attachments are created or sent** for the SEPA direct debit procedure. This is the intended way to disable the function.

> [!NOTE]
>
> The source documentation specifies the default `SEPA-DirectMandate_~BANK-IBAN~_~WS-OrderID~.pdf` for both file names. In the kernel, however, the fallback value for the business mandate file name is simply `SEPA-DirectMandate.pdf`. Don't rely on the default; enter the file name you want instead.

For the headers and footers of the two mandate PDFs, the kernel reads eight additional parameters that aren't described in the previous documentation.

| Parameter | Purpose |
| - | - |
| `SEPACustomerPDFHeaderURL`, `SEPACompanyPDFHeaderURL` | URL of the header |
| `SEPACustomerPDFFooterURL`, `SEPACompanyPDFFooterURL` | URL of the footer |
| `SEPACustomerPDFHeaderMargin`, `SEPACompanyPDFHeaderMargin` | Distance of the header from the page edge |
| `SEPACustomerPDFHeaderSpacing`, `SEPACompanyPDFHeaderSpacing` | Distance of the header from the content |
| `SEPACustomerPDFFooterMargin`, `SEPACompanyPDFFooterMargin` | Distance of the footer from the page edge |
| `SEPACustomerPDFFooterSpacing`, `SEPACompanyPDFFooterSpacing` | Distance of the footer from the content |

The four spacing parameters per mandate type are only evaluated if the associated URL is filled in.

### `MerchantOrderMail`

The order notification email to the merchant.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<MerchantOrderMail>
   Allow         = yes
   Address       = bestellungen@mein-shop.de,lager@mein-shop.de
   Subject-Txt   = Neue Bestellung ~OrderNumber~ von ~FirstName~ ~LastName~
   SenderAddress = shop@mein-shop.de
   SenderName    = Mein Shop
   Template      = mail_merchant_order.htm
</MerchantOrderMail>
```

| Parameter | Purpose | Values |
| - | - | - |
| `Address` | Recipient. Multiple addresses comma-separated | Email addresses |

Five local tags are available in the subject.

| Tag | Output |
| - | - |
| `FirstName` | First name |
| `LastName` | Last name |
| `OrderNumber` | Order receipt identifier |
| `ShopID` | ShopID |
| `SubShopID` | SubShopID |

### `OrderInfoMail`

Info emails triggered via the SOAP V2 interface.

| Parameter | Purpose | Values |
| - | - | - |
| `BCC-Address` | Address for a blind copy. Multiple comma-separated | Email addresses |

Everything else corresponds to the common blueprint including `Allow`.

## Follow-up and reminders

### `OrderNowMail`

The BackInStockMail, formerly the OrderNow service. It notifies registered customers as soon as a product is available again.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<OrderNowMail>
   Allow         = yes
   Subject-Txt   = ~PR-Name~ ist wieder verfügbar
   SenderAddress = shop@mein-shop.de
   SenderName    = Mein Shop
   Template      = mail_ordernow.htm
   Referer       = backinstock
   SubReferer    =
</OrderNowMail>
```

| Parameter | Purpose | Values |
| - | - | - |
| `Referer` | Optional referer appended to the product link | Text |
| `SubReferer` | Optional subreferer appended to the product link | Text |

These local tags are available in the subject.

| Tag | Output |
| - | - |
| `A-E-Mail` | Email address |
| `A-FirstName` | First name |
| `A-LastName` | Last name |
| `A-Salutation` | Salutation, for example Ms. |
| `A-CompleteSalutation` | Full salutation, for example Dear Ms. Mustermann |
| `PR-Name` | Product name |
| `PR-Number` | Item number |
| `DeepLink` | General deep link |
| `PR-DeepLink` | Deep link to the product |

The two referer parameters make visible in the analytics how many orders result from these notifications.

### `RateRemindMail`

Rating reminders by email. Supports the common blueprint including `Allow`.

> [!WARNING]
>
> For the rating reminder, only a template from the subshop folder of the respective subshop can be used. The template must therefore be created individually for each subshop and entered here.

### `ProdRecmdMail`

Email of the "Recommend product" function. Only supports `Template` as well as `UseExternMailSystem` and `ExternMailTemplate`. Sender and subject result from the function itself.

### `WishListMail`

Email for sending a wish list. Supports only `Template`.

### `SendUploadLinkMail`

Email with the links to the upload module. Supports the common blueprint without `Allow`, plus `UseExternMailSystem` and `ExternMailTemplate`. `SenderName` is optional.

> [!WARNING]
>
> The content of this template goes to an email address entered by the customer. For data protection reasons, pay attention to which data you output there.

## `+Newsletter`

Enables newsletter sign-up during the checkout process. A separate `+Newsletter` section is created for each target group or newsletter list.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<+Newsletter>
   Allow            = yes
   Name-Txt         = Unser wöchentlicher Newsletter
   Checkbox         = off
   NewsletterID     = 1
   GroupID-List     = 12,15
   NotificationMode = order
   Type             = WSNewsletterV3
</+Newsletter>
```

| Parameter | Purpose | Values |
| - | - | - |
| `Allow` | Entry active. With `no`, the selection doesn't appear at all | `yes`, `no`. Default: `no` |
| `Name-Txt` | Freely selectable name of the newsletter | Text |
| `Checkbox` | Default state of the checkbox | `on`, `off`. Default: `on` |
| `NewsletterID` | Unique identifier for bracketings in the template | Number |
| `GroupID-List` | Target group index values from the E-Marketing Manager | Numbers, comma-separated |
| `NotificationMode` | When the registration is triggered | `order`, `immediate`. Default: `order` |
| `Type` | Newsletter type | `WSNewsletter`, `WSNewsletterV3`, `MailTemplate`. Default: `WSNewsletter` |
| `Template` | Email template, only required with `Type = MailTemplate` | Template name |
| `ListServerAddress` | Subscribe address of the newsletter | Address |

`NotificationMode = order` starts the registration when the order is generated, `immediate` as soon as the page changes.

`ListServerAddress` is only needed for the WEBSALE Newsletter V1 and for external providers that support such an address.

> [!WARNING]
>
> If the name of a target group changes in the E-Marketing Manager, `Name-Txt` must also be adjusted here. The two places aren't synchronized automatically.
>
> The privacy-compliant setting for `Checkbox` is `off`, even though the default is `on`.

In addition, the section supports `UseExternMailSystem` and `ExternMailTemplate`.

## `GenericEmails`

For everything that doesn't have its own section. One `+Entry` subsection per email, up to 20.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<GenericEmails>
   <+Entry>
      ID            = ruecksendung
      Address       = retouren@mein-shop.de
      Subject-Txt   = Rücksendung angemeldet
      SenderAddress = shop@mein-shop.de
      SenderName    = Mein Shop
      Template      = mail_ruecksendung.htm
   </+Entry>
</GenericEmails>
```

| Parameter | Purpose | Values |
| - | - | - |
| `ID` | Unique identifier of the notification | Characters and digits |
| `Address` | Recipient. Multiple comma-separated | Email addresses |
| `Subject-Txt` | Subject | Text |
| `SenderAddress` | Sender address | Email address |
| `SenderName` | Sender name | Text |
| `Template` | Email template | Template name |
| `UseIndividualRecipientAddress` | Determine the recipient at runtime instead of from `Address` | `yes`, `no`. Default: `no` |

> [!NOTE]
>
> `UseIndividualRecipientAddress` isn't described in the previous documentation and is added here.

> [!WARNING]
>
> For this section, the kernel does **not** read `UseExternMailSystem` and `ExternMailTemplate` from the individual `+Entry`, but from the level above it, that is, directly below `GenericEmails`. A setting within `+Entry` has no effect, and the setting then applies to all entries together.
>
> The previous documentation shows both parameters within `+Entry`. Whether this is intentional or a bug in the kernel is yet to be clarified. Until then, set both parameters at the section level.

## `ShopAdminMail`

Notifications about problems in ongoing shop operation to the shop administrator.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<ShopAdminMail>
   Allow   = yes
   Address = admin@mein-shop.de,technik@mein-shop.de
</ShopAdminMail>
```

| Parameter | Purpose | Values |
| - | - | - |
| `Allow` | Enable sending of important notifications | `yes`, `no`. Default: `no` |
| `Address` | Recipient. Multiple comma-separated | Email addresses |

This section has neither subject nor template. The shop specifies both.

## Additional email sections

These emails thematically belong to other functions and are described there.

| Section | Belongs to |
| - | - |
| `BestPrice-PreorderMail`, `BestPrice-OrderErrorMail` | BestPrice order module |
| `ProductsInAction-Mail` | Products In Action |
| `Subscription` with its four mail subsections | Subscription module |


## Related topics

- [Emails & email settings](https://dokumentation.websale.de/en/konfiguration/e-mails-e-mail-einstellungen.md)
- [$wsEmails - Emails](https://dokumentation.websale.de/en/frontend/referenz/module/wsemails.md)
- [Custom emails](https://dokumentation.websale.de/en/v8s/e-mails/benutzerdefinierte-e-mails.md)
- [Email notifications: overview](https://dokumentation.websale.de/en/v8s/e-mails/e-mail-benachrichtigungen-ueberblick.md)
- [messages - Event-driven emails](https://dokumentation.websale.de/en/konfiguration/messages-ereignisgesteuerte-e-mails.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.