Integrating Inxmail - WEBSALE Dokumentation

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:

After the order, the shop sends the predefined order data to Inxmail.
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.

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

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.

<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

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.

{
  "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}
    ]
  }
}

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.

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

"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}
]

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.

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

<CustomerMail>
   ...
   UseExternMailSystem = InxMail
   ...
</CustomerMail>

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:

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

The log entries are JSON objects. The logs are kept for a maximum of six months and then deleted automatically.

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.

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

​How sending works

​Which emails can run via Inxmail

​Setup

​Preparation

​Step 1: Activation

​Step 2: Adjusting the shop.config

​Step 3: Creating the email templates

​Passing PDF files

​Step 4: Testing sending

​Step 5: Going live

​Intervening in case of errors

​Related topics

How sending works

Which emails can run via Inxmail

Setup

Preparation

Step 1: Activation

Step 2: Adjusting the shop.config

Step 3: Creating the email templates

Passing PDF files

Step 4: Testing sending

Step 5: Going live

Intervening in case of errors

Related topics