Setting up email imports for Online Bookings

Setting up email import for Online Bookings^M^M

Enquiries and bookings made via the online booking system can either be imported directly into Bp Event or sent by email first and then imported once they have been checked by a user.
The import method available depends on the modules installed. Direct import is possible using the ‘WebApp Access’ module; alternatively, set up email import. If only the ‘Email Bookings" module is available, email import is the only option.
Email import can also be useful if the Bp Event web server is not intended to be publicly accessible, or if incoming enquiries and orders need to be checked before they are entered into Bp Event.

During the email import, the web app sends the data entered to a mailer on a PHP-enabled web server. The mailer then sends:

an import email to the specified import address,
a brief notification to the customer upon receipt.

The import email contains a readable preview of the details provided. The user checks the data in Bp Event and then decides whether to start the import.

The full enquiry or booking confirmation will only be sent once the import from Bp Event has been successfully completed. The email import is activated company-wide and will then apply to all of the company’s online booking apps.

Set-up on the external web server is carried out by the customer or their technical service provider. This includes, in particular:

Installation and configuration,
Adaptation to the server and email environment,
Secure the endpoint
Monitor ongoing operations
Maintenance and updating of production files.

Customised mailer files are not covered by standard support.

Alternatively, the set-up of the external host or file synchronisation can be commissioned as a separate, chargeable service from Bankettprofi’s IT Services.

Select the web server for the web app
The Mailer must be run on an external PHP-enabled web server, as the Bp Event web server does not execute PHP. However, the WebApp itself can be run on the Bp web server.

Option 1: Web app on the Bp Event web server

This option requires the ‘WebApp Access’ module.
The ‘Online Booking’ and ‘bpWebApp’ folders remain on the Bp Event web server; only the mailer is set up on an external host.

This option is suitable if the Bp Event web server is accessible and you wish to use functions that require direct access to up-to-date data from Bp Event. As the WebApp and Mailer are hosted on different domains, communication between the two servers must be enabled.

Option 2: Web app and mailer on an external host

The ‘Online-Buchung’ and ‘bpWebApp’ folders, as well as the mailer, are hosted on the external web server.

This option is required if the Bp Event web server is not intended to be, or cannot be, publicly accessible. The WebApp files exported from Bp Event must then be synchronised regularly with the external host.

Functions that require direct access to current data in Bp Event are not available in this version.
Prepare the production Mailer file
The standard online booking scenario provides two technical templates in the Online Booking/mailer folder to facilitate the set-up of the email import:
1. mailer.php receives the data transmitted by the web app and sends the import email and a brief notification of receipt to the customer.
2. mailer.css contains the styling for the email content being sent.
However, the files are NOT intended for use as a permanently managed customer installation, as they will be overwritten during a scenario update. They may be adopted or replaced with your own compatible implementation.

Copy the template files before making any changes and edit only the production copy. Use a different file name or a separate folder for the production installation, for example:

Online-Buchung/mailer/customer-mailer.php
Online-Buchung/mailer/customer-mailer.php

Alternatively, you can use a fully customised, compatible email client solution. In particular, a custom implementation must:
- accept the data transmitted by the web app
- generate an import email in the expected format,
- specify the import job WebApp_Online-Buchung_Import_00_Transaktion,
- transmit the data required for the import without any changes,
- send the brief confirmation of receipt to the customer.
Install the PHPMailer library
The PHPMailer library is not included in the online booking system and must be made available separately on the external web server. Use the version that has been tested and specified for the current mailer template.

Install PHPMailer with or without Composer:
1. If Composer is available, use it to install the specified version of PHPMailer. Composer provides all the necessary files in full within the ‘vendor’ folder and documents the version used.
2. Alternatively, download the appropriate PHPMailer release from the official PHPMailer project.
  1. Copy the entire ‘src’ folder and the associated licence file into the directory containing the production Mailer file. Only use files from the same release and do not mix different versions of PHPMailer.
Composer does not need to be installed on the production web server. The library can be set up on a different system and then transferred in its entirety to the external host.

Do not update PHPMailer without first checking that it works correctly. After installation or an update, check that the import email and the receipt notification are sent correctly by making a test booking.

Set up email delivery

The mailer supports sending via SMTP or Sendmail. Please store the required settings as server-side environment variables rather than directly in the PHP file. This ensures that login details remain secure and allows the mailer file to be updated independently of the server configuration.

Configure the general settings.
The following details are used regardless of the email transport method selected:

Variable	Meaning	Standard value
MAIL_FROM_ADDRESS	Sender address of the emails sent	-
MAIL_IMPORT_RECIPIENT	Email address to which the import email is sent	-
MAIL_FROM_NAME	Displayed sender name	Online Bookings
MAIL_IMPORT_SUBJECT	Fixed subject line of the import email	is generated automatically
MAIL_CSS_FILE	Full path to the production CSS file	mailer.css (next to the PHP file)

MAIL_FROM_ADDRESS and MAIL_IMPORT_RECIPIENT are mandatory fields and must contain valid email addresses.

If MAIL_IMPORT_SUBJECT is not set, the mailer automatically generates the subject line based on the language, the transaction type and the title of the online booking.
If MAIL_CSS_FILE is not set, the mailer expects the file mailer.css to be in the same directory as the PHP file.
If you are using your own CSS file, enter its full path.

Set up email delivery either via SMTP or via Sendmail. SMTP is the recommended option.

Option 2: Set up email delivery using Sendmail

The mailer logs in to a mail server using a user account. Please also enter the following settings:

Variable	Meaning	Standard value
MAIL_TRANSPORT	Email transport	smtp
SMTP_HOST	Name of the SMTP server	-
SMTP_USER	SMTP account username	-
SMTP_PASS	SMTP account password	-
SMTP_PORT	SMTP server port	587
SMTP_SECURE	Encryption: starttls or smtps	starttls

This template only supports SMTP with authentication. SMTP_HOST, SMTP_USER and SMTP_PASS are therefore mandatory.
Common combinations are:
Port 587 with starttls
Port 465 with SMTPS

You can obtain the correct connection details from the mail server operator. Use a sender address that is authorised for the SMTP account you are using.
Example:
MAIL_TRANSPORT=smtp
MAIL_FROM_ADDRESS=This email address is being protected from spambots. You need JavaScript enabled to view it.
MAIL_FROM_NAME=Online-Buchung
MAIL_IMPORT_RECIPIENT=This email address is being protected from spambots. You need JavaScript enabled to view it.
MAIL_CSS_FILE=/full/path/customer-mailer.css

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=smtp-user
SMTP_PASS=GEHEIMES-PASSWORT
SMTP_SECURE=starttls

Option 2: Set up email delivery using Sendmail

Only use Sendmail if a fully functional local mail delivery system is already set up on the external web server. This is set up by the customer’s IT department or the hosting provider.

Configure the following settings:
MAIL_TRANSPORT=sendmail
MAIL_FROM_ADDRESS=This email address is being protected from spambots. You need JavaScript enabled to view it.
MAIL_FROM_NAME=Online-Buchung
MAIL_IMPORT_RECIPIENT=This email address is being protected from spambots. You need JavaScript enabled to view it.
MAIL_CSS_FILE=/full/path/customer-mailer.css
The variables SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS and SMTP_SECURE are not used with Sendmail. There is no need to specify a separate Sendmail path; PHPMailer uses the existing server configuration.

Save the settings securely. It is recommended that you store the environment variables as follows:
1. in the hosting control panel,
2. in the web server or PHP-FPM configuration, outside the publicly accessible web directory,
3. in Apache, or alternatively in a protected .htaccess file.

In particular, do not store the SMTP password in mailer.php, mailer.css or any other publicly accessible file.
If you are using nginx or your own PHP-FPM configuration, the customer’s IT team will set up the variables in line with the server environment. Following any changes, it may be necessary to restart PHP, PHP-FPM or the web server. You should then check whether PHP can actually read the variables.

Enable communication between the WebApp and the mailer
If the web app and the mailer are hosted on different domains, the external web server must allow requests from the web app’s domain. To do this, set up the appropriate CORS authorisation.

Important:
- Only authorise the domains of the web app that are actually in use.
- Do not use a general share for any domains.
- Allow the POST requests required for the transmission.
- Make sure that any required OPTIONS requests are answered.
- Check whether a firewall, hosting protection or security modules are blocking the request.
The specific configuration depends on the version of the web server and mailer being used. The permitted domains are defined in accordance with the configuration of the mailer template provided.
Once you have set it up, check that the communication is working by making a test booking.
Deploy the WebApp externally and synchronise the files
This step is only necessary if, in addition to the mailer, the web app is also hosted on an external web server.

Transfer the following folders from the Bp Event web server to the external host:
- Online Bookings
- bpWebApp
The ‘Online-Buchung/Templates’ folder contains the individual apps, along with their logic and the data exported from Bp Event.

Following changes in Bp Event and a subsequent export, the updated files must be transferred to the external host. Synchronisation can be carried out manually or automatically. One possible technical solution is to use WinSCP FileTransport.

Make sure that:
- the directory structure is retained,
- new and modified files are transferred in full,
- the web app is then accessible via HTTPS,
- the production Mailer file and its configuration are not overwritten,
- Transmission errors are logged and checked.
The customer’s IT department is responsible for setting up the transfer. Alternatively, Bankettprofi’s IT services can be commissioned as a separate, chargeable service.
Enter the Mailer URL in Bp Event
If only the “Email Enquiries” module is available, email importing is the only option. In this case, enter a mailer URL in the URL for Email Import field in the “Companies” table.

The ‘WebApp Access’ module allows you to choose between direct import and email import. If the field is left blank, a direct import will be the default. If a mailer URL is entered, the data from all of this company's online booking apps will be imported from email.

Enter the URL of the production mailer file.

Examples:
https://website-domain/Online-Buchung/mailer/customer-mailer.php
or if you have a suitable shared directory structure:
../../mailer/customer-mailer.php

Use a full HTTPS address where possible.
If the ‘WebApp Access’ module is active, you can switch back to direct import by clearing the field ‘ ’ URL for email import , saving your changes, and then populating the apps.
Set up the import email account in Bp Event
If a suitable email inbox account has not yet been set up in Bp Event, first create the email server and the required email account. (Setting up email accounts)
Bp Event must be able to retrieve the import address stored in the Mailer configuration.
Email booking processing is already included with the ‘WebApp Access’ module. There is no need to activate this module separately.
Try out the full setup
Once the setup is complete, carry out a full test booking using test data and test email addresses. Check the following:
1. The web app can access the production Mailer file.
2. The import email arrives at the specified import address.
3. The customer receives a brief confirmation of receipt.
4. Bp Event retrieves the import email.
5. A readable preview is displayed in the HTML tab.
6. The import can be started using the integrated action ‘WebApp_Online-Buchung_Import_00_Transaktion’.
7. The event, along with the associated addresses, rooms, segments and items, will be created correctly.
8. The designated users will be notified.
9. Following the import, the customer will receive the full enquiry or order confirmation.
10. Any invoices that may be required will be prepared and dispatched correctly.
Please note: The import email is not automatically archived or filed when the event is created; instead, it is marked as read.
Check for errors and logs
If a transmission has failed, check the following first:
- Accessibility of the mailer URL
- HTTPS certificate
- CORS authorisation for different domains
- PHP and Web Server Protocol
- SMTP or mail server protocol
- Environment variables
- Sender and import address
- Firewall and outbound SMTP connection
- PHP version and required PHP extensions
- post_max_size
- File permissions for PHP, CSS and PHPMailer files.
Typical messages:
- Server configuration incomplete
  A required environment variable is missing, or the configured CSS file is unreadable.
- SMTP configuration incomplete
  SMTP_HOST, SMTP_USER or SMTP_PASS is missing.
- Invalid email configuration
  An email address, the SMTP port, the encryption or the mail transport is invalid.
- Transaction ID not found
  The transaction data provided is missing the UUID required for the import.
- Booking details could not be transmitted
  The mail server could not be reached or did not accept the import email. Further information can be found in the server log.
- HTTP-Status 405
  The Mailer file was not accessed using the intended POST request.
Future maintenance of the Mailer solution
Changes made to the templates provided are not automatically incorporated into the customer’s live system. The maintenance of customised mailer files is the responsibility of the customer or their technical service provider and is not covered by standard support.
1. Check whether any relevant adjustments have been made following a scenario update.
2. Back up the production files before making any changes and implement new features in a controlled manner within your own implementation.
3. Only update PHPMailer to a complete, matching version and then carry out a test transaction.

Setting up email imports for Online Bookings

Setting up email import for Online BookingsMM

Setting up email import for Online Bookings^M^M