> ## 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.

# Integrating Inxmail

> Send transactional emails such as order confirmations via Inxmail Commerce, switchable individually for each email type.

Order confirmations, shipping confirmations and password emails are expected and therefore opened. Anyone who wants to make use of this attention needs a consistent design and reliable figures on opens and clicks. Inxmail Commerce takes over design and sending for this, while the data continues to come from the shop.

The switch is made individually for each email type. For each type, you decide whether it continues to run via the WEBSALE email system or via Inxmail.

## How sending works

Using the order confirmation as an example:

1. After the order, the shop sends the predefined order data to Inxmail.
2. Inxmail inserts this data into the email template stored there and sends the email to the buyer.

If sending fails, the shop tries again. The interval between attempts can be configured by WEBSALE.

> [!WARNING]
>
> If sending ultimately fails, the merchant has to intervene. This task will come up and must be assigned to someone, otherwise order confirmations will go unnoticed. How to intervene is described in the last section.

## Which emails can run via Inxmail

| Email | Section in the `shop.config` |
| - | - |
| Welcome email | `RegistrationMail` |
| Order confirmation | `CustomerMail` |
| Confirm new customer registration | `NewCustomerDoubleOptInMail` |
| Confirm email address change | `ChangeEmailDoubleOptInMail` |
| Voluntarily confirm email address | `CustomerVoluntaryDoubleOptInMail` |
| Confirm account deletion | `DeleteAccountDoubleOptInMail` |
| Reset password | `SetPasswordMail` |
| Send upload link | `SendUploadLinkMail` |
| Generic email sending | `GenericEmails` |
| Recommend product | `ProdRecmdMail` |
| Newsletter subscription in the checkout process | `+Newsletter` |

Emails related to INQUIRY forms run via the form's configuration.

Guide: Forms for customer inquiries

## Setup

### Preparation

First clarify with Inxmail Commerce which of their services you want to use, and pass this scope on to WEBSALE. This is the only way to determine in advance whether the interface can cover everything you are planning. You also make the settings on the Inxmail side in advance.

### Step 1: Activation

The function must be set up by WEBSALE for your shop ID. Three details are required for this:

* Key
* Secret
* URL

> [!NOTE]
>
> If you have requested a separate test account from Inxmail, also pass on its access credentials.

### Step 2: Adjusting the shop.config

For each email that is to run via Inxmail, the corresponding section is extended.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<CustomerMail>
   ...
   Allow               = yes
   ExternMailTemplate  = customer_mail.inxmail
   UseExternMailSystem = InxMail_Test
   ...
</CustomerMail>
```

| Parameter | Meaning |
| - | - |
| `ExternMailTemplate` | Name of the template that compiles the data for Inxmail |
| `UseExternMailSystem` | `InxMail_Test` for the test phase, `InxMail` for production |

> [!NOTE]
>
> `InxMail_Test` is not available for INQUIRY forms. Use a separate `inquiry-cfg` for the test phase.

### Step 3: Creating the email templates

A separate template is created in your template directory for each email type. The data is passed as JSON, so the template builds a JSON object. Refer to the Inxmail documentation for which details it must contain.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "event": "neworder",
  "payload":
  {
    "Customer":
    {
      "Id": "~A-Number~",
      "Email": "~A-EMail~"
      {!ST-KnownCustomer},"IsNewCustomer": true{/!ST-KnownCustomer}
    },
    "Order":
    {
      "Id": "~WS-OrderNumber~",
      "Date": "~WS-OrderDate~ ~WS-OrderTime~"
    },
    "Items":
    [
      {@BASKET-PR-Data}
        {DC-CompareDigitGT($BASKET-PR-Position$,1)},{/DC-CompareDigitGT($BASKET-PR-Position$,1)}
        {
          "Sku": "~BASKET-PR-Number~",
          ~DC-FP1_set($BASKET-PR-Name$)~
          "Name": "~DC-FP1_jsonencoding~",
          "Price": ~BASKET-PR-TechnicalSum~,
          "Currency": "~WS-Currency~"
        }
      {/@BASKET-PR-Data}
    ]
  }
}
```

> [!WARNING]
>
> Amounts belong in a technical format, i.e. without thousands separators and with a period as the decimal separator. The formatted price from the shop makes the JSON invalid as soon as an amount has four digits.

> [!NOTE]
>
> Product names can contain quotation marks and umlauts and must therefore go through `DC-FP1_jsonencoding`. Without this step, a single quotation mark in a product name breaks the entire transfer.

All tags that are available on the regular email templates are allowed on these templates, plus dedicated tags for external mail systems.

Reference: DC-FPX\_jsonencoding · MAIL tags

Guide: Email notifications · Exchanging data with external systems

#### Passing PDF files

There are three ways to pass attachments:

| Way | Used for |
| - | - |
| static PDF file base64-encoded as fixed text | an attachment that never changes, for example the cancellation policy |
| ready-made base64 code | files configured as a static attachment |
| HTML between two markers | the interface generates a PDF from it itself |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
"attachments":
[
  {@MAIL-FileAttachment}
    {
      "filename": "~MAIL-FileAttachment_Name~",
      "content-type": "application/pdf",
      "content": "~MAIL-FileAttachment_ContentB64~"
    },
  {/@MAIL-FileAttachment}
  {@MAIL-HTMLAttachment}
    {
      "filename": "~MAIL-HTMLAttachment_Name~",
      "content-type": "application/pdf",
      "content": "WEBSALE-EXTMAIL-HTML2PDFB64::~MAIL-HTMLAttachment_ContentB64~::WEBSALE-EXTMAIL-HTML2PDFB64"
    }
  {/@MAIL-HTMLAttachment}
]
```

> [!NOTE]
>
> The content between `WEBSALE-EXTMAIL-HTML2PDFB64::` and `::WEBSALE-EXTMAIL-HTML2PDFB64` is converted into a PDF by the interface. This lets you generate an invoice from an HTML template, for example, without using a separate PDF tool.

Reference: MAIL-FileAttachment\_ContentB64 · MAIL-HTMLAttachment\_ContentB64

### Step 4: Testing sending

Open the shop in the general test mode, trigger the respective email and check whether it arrives and its content is correct.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.ihr-shop.de/?test=on
```

After testing, switch the test mode off again.

Guide: Switching the shop's test modes on and off

### Step 5: Going live

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<CustomerMail>
   ...
   UseExternMailSystem = InxMail
   ...
</CustomerMail>
```

> [!NOTE]
>
> If you worked with a separate test account at Inxmail, contact your WEBSALE contact person after testing. WEBSALE will then switch to the access credentials of the production account.

## Intervening in case of errors

The feature includes a dedicated FTP account for an error directory with this structure:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
/errors
/spool
/log
```

| Directory | Content |
| - | - |
| `/errors` | one file per failed call, containing the data that was to be sent |
| `/log` | one file `JJJJMMTT.log` per day with all messages, including those from Inxmail |
| `/spool` | files that are to be transferred again |

How to handle an error: find the affected file in `/errors`, look up the corresponding message in the log, correct the data and move the file to `/spool`. Everything in `/spool` is transferred to Inxmail again. If it fails again, the file moves back to `/errors`.

> [!NOTE]
>
> The log entries are JSON objects. The logs are kept for a maximum of six months and then deleted automatically.

> [!NOTE]
>
> A REST interface can be used to query the number of errors in the last few minutes. This lets you set up monitoring instead of keeping an eye on the directory manually.

## Related topics

* Guide: Email notifications
* Guide: Forms for customer inquiries
* Guide: Exchanging data with external systems


## Related topics

- [Integrating FINDOLOGIC](https://dokumentation.websale.de/en/v8s/externe-dienste/integration-von-findologic.md)
- [Integrating tracking](https://dokumentation.websale.de/en/v8s/funktionen-zur-shop-optimierung/tracking-einbinden.md)
- [External services: Overview](https://dokumentation.websale.de/en/v8s/externe-dienste/externe-dienste.md)
- [Integrating external content](https://dokumentation.websale.de/en/v8s/externe-dienste/externe-inhalte-einbinden.md)
- [Emails](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/e-mails.md)


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