Emails - WEBSALE Dokumentation

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.

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.

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.

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

<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

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.

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

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.

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

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.

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.

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

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

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.

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.

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

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

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.

<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`

UseIndividualRecipientAddress isn’t described in the previous documentation and is added here.

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.

<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

​The common blueprint

​Sending via an external mail system

​Registration and customer account

​RegistrationMail

​NewCustomerMail

​NewCustomerDoubleOptInMail

​CustomerVoluntaryDoubleOptInMail

​ChangeEmailDoubleOptInMail

​DeleteAccountDoubleOptInMail

​SetPasswordMail

​Order

​CustomerMail

​Order details as PDF attachment

​Additional file attachments

​SEPA mandates

​MerchantOrderMail

​OrderInfoMail

​Follow-up and reminders

​OrderNowMail

​RateRemindMail

​ProdRecmdMail

​WishListMail

​SendUploadLinkMail

​+Newsletter

​GenericEmails

​ShopAdminMail

​Additional email sections

The common blueprint

Sending via an external mail system

Registration and customer account

`RegistrationMail`

`NewCustomerMail`

`NewCustomerDoubleOptInMail`

`CustomerVoluntaryDoubleOptInMail`

`ChangeEmailDoubleOptInMail`

`DeleteAccountDoubleOptInMail`

`SetPasswordMail`

Order

`CustomerMail`

Order details as PDF attachment

Additional file attachments

SEPA mandates

`MerchantOrderMail`

`OrderInfoMail`

Follow-up and reminders

`OrderNowMail`

`RateRemindMail`

`ProdRecmdMail`

`WishListMail`

`SendUploadLinkMail`

`+Newsletter`

`GenericEmails`

`ShopAdminMail`

Additional email sections