Protel – End User Manual

Overview

The Protel Manager integration connects a Protel hotel management system with Maileon email marketing. It receives guest profile and reservation events from Protel in real time, creates and updates contacts in Maileon, and sends reservation transactions that can trigger automated email workflows.

Availability: Currently only Protel On-Premise is available and supported. Protel Air support is planned but not yet released.

Setup and Configuration

Configuration is managed per hotel account. Each hotel account has one settings record that controls all integration behaviour for that account.

You can find the settings in your Maileon account: Settings → Plugins → Protel

Required Settings

Setting	Description

Setting	Description
Maileon API Key	API key for the Maileon account where contacts and transactions are written.
Protel Bearer Token	Authentication token this application uses when sending data back to Protel.
Maileon Bearer Token	Authentication token Protel must include when sending events to this application. Must be configured on the Protel side.
Product	Protel variant: `on-premise`.
Hotel ID	The hotel's identifier in Protel.

Contact and Subscription Settings

Setting	Default	Description

Setting	Default	Description
Initial Permission	`1`	The Maileon permission level assigned to new contacts (1–6).
DOI Process	off	Enable Double Opt-In for newly created contacts. When enabled, Maileon sends the configured DOI mailing to the guest.
DOI Plus	off	Enable DOI+ variant instead of standard DOI.
DOI Key	—	The key identifying the DOI mailing to send. Required when DOI Process is enabled.
Deactivate for Import	off	When enabled, no contacts are created or updated and no DOI mailings are triggered. Use during bulk imports to prevent unwanted DOI sends.

Reservation Transaction Settings

Setting	Default	Description

Setting	Default	Description
Send Transactions to Guest	off	When enabled, reservation transactions are also sent to the arriving guest's email address, not only to the booker.

Each reservation transaction type can be enabled or disabled independently. All are disabled by default.

Setting	Transaction Sent

Setting	Transaction Sent
Reservation Requested enabled	`protel_reservation_requested`
Reservation Waitlisted enabled	`protel_reservation_waitlisted`
Reservation Reserved enabled	`protel_reservation_reserved`
Reservation In House enabled	`protel_reservation_in_house`
Reservation Checked Out enabled	`protel_reservation_checked_out`
Reservation Cancelled enabled	`protel_reservation_cancelled`
Reservation No Show enabled	`protel_reservation_no_show`
Reservation Data Changed enabled	`protel_reservation_data_changed`

Required Maileon Account Settings

The following settings must be disabled in Maileon to prevent unwanted DOI mailings from being re-sent on every profile update:

Allow DOI process restart if the contact has not yet completed it successfully — must be disabled
Permission update: Allow DOI process despite existing double opt-in permission — must be disabled

Events from Protel

Guest Created

Triggered when a new guest profile is added in Protel.

When the contact is created in Maileon:

For Protel On-Premise, the guest profile must meet all of the following conditions:

The global marketing opt-out flag (ShareAllOptOutInd) must not be set to Yes
The guest must have a default private email address (email type 1) with the per-email marketing consent flag (ShareMarketInd) set to Yes

If any condition is not met, no contact is created in Maileon.

When DOI is triggered:

DOI is sent only if all of the following are true:

DOI Process is enabled in settings
The contact does not already exist in Maileon with a completed DOI or DOI+ permission
This combination of email address and Protel guest ID has not had a previous subscription attempt recorded for this account
Deactivate for Import is not enabled

If the contact already exists with DOI or DOI+ permission, the contact data is updated but no new DOI mailing is sent.

Fields set in Maileon when a contact is created or updated:

Standard fields (built into every Maileon account):

Maileon Standard Field	Source in Protel	Notes

Maileon Standard Field	Source in Protel	Notes
Email	Default private email address (email type 1)	On-Premise: `ShareMarketInd = Yes` and `DefaultInd = true` required
Permission	Configured Initial Permission setting	Set on creation; not overwritten if contact already has DOI or DOI+ permission
`FIRSTNAME`	Guest first name
`LASTNAME`	Guest last name
`TITLE`	Guest name title
`SALUTATION`	Salutation from guest profile extensions
`GENDER`	Guest gender	Mapped: `Male` → `m`, `Female` → `f`, unknown values cleared
`LOCALE`	Guest language	Normalised to two-letter ISO 639-1 code; cleared if not a recognised language
`BIRTHDAY`	Guest birth date
`ADDRESS`	Guest address line
`HNR`	Guest street number
`ZIP`	Guest postal code
`CITY`	Guest city
`COUNTRY`	Guest country

Custom fields (created by the plugin in the Maileon account):

Maileon Custom Field	Source in Protel	Notes

Maileon Custom Field	Source in Protel	Notes
`protel_phonenumber`	Guest landline phone number	On-Premise: `ShareMarketInd = Yes` required; default-flagged number takes priority if multiple exist
`protel_mobilenumber`	Guest mobile phone number	On-Premise: `ShareMarketInd = Yes` required; default-flagged number takes priority if multiple exist
`protel_keywords`	Keywords assigned to guest (context: protelIO, type: KEYWORD)	Comma-separated list
`protel_marketing_codes`	Marketing codes assigned to guest (context: protelIO, type: MARKETINGCODE)	Comma-separated list
`protel_vip_codes`	VIP codes assigned to guest (context: protelIO, type: VIPCODE)	Comma-separated list

Guest Profile Updated

Triggered when an existing guest's data changes in Protel (e.g. email address, name, address, phone number, marketing codes).

Subscription logic: The same marketing consent flags are evaluated again. If they now indicate opt-out, the contact is unsubscribed in Maileon. If they indicate opt-in and the contact does not yet have DOI or DOI+ permission, DOI is triggered subject to the same conditions as above.

Fields updated in Maileon: the same fields as listed under Guest Created above.

Reservation Changed

Triggered when a reservation is created, modified, or its status changes in Protel.

The integration tracks the state of each reservation. On each incoming event it compares the new data against the last known state to determine which transaction to send.

Status change transactions — one sent per status transition, if the corresponding setting is enabled:

New Reservation Status	Transaction Sent

New Reservation Status	Transaction Sent
Requested	`protel_reservation_requested`
Waitlisted	`protel_reservation_waitlisted`
Reserved / Confirmed	`protel_reservation_reserved`
In House (checked in)	`protel_reservation_in_house`
Checked Out	`protel_reservation_checked_out`
Cancelled	`protel_reservation_cancelled`
No Show	`protel_reservation_no_show`

Data change transaction — sent when the status did not change but one of the following changed:

Arrival date
Departure date
Number of guests (any category: adults, children, infants, teenagers, juniors, seniors)
Guest contact email
Rates

Transaction sent: protel_reservation_data_changed

Events that are ignored:

Duplicate events: if Protel sends the same event twice with the same modification timestamp, the duplicate is discarded.
Out-of-order events: if an event is older than the last processed event for the same reservation, it is discarded.
Events where the guest profile is not a customer profile.

Unsubscription Forwarded from Maileon to Protel

When a guest unsubscribes in Maileon, the unsubscription is automatically forwarded to Protel to keep the marketing consent flags in sync. No manual action is required.

For Protel On-Premise, the following is updated in Protel upon unsubscription:

The per-email marketing consent flag (ShareMarketInd) is set to No on the guest's email address in Protel.

Conditions for the unsubscription to be forwarded:

The contact must have had a completed DOI or DOI+ permission in Maileon. Contacts that never completed DOI are not affected.
Deactivate for Import must not be enabled.

Data Sent to Maileon

Transaction Attributes

All reservation transaction types carry the same set of attributes:

Attribute	Type	Description

Attribute	Type	Description
`transaction_id`	String	Unique identifier for this transaction.
`reservation_number`	String	Reservation number from Protel.
`changed_data`	JSON	Which data fields changed (populated for data-changed transactions).
`start_date`	Date	Arrival date.
`end_date`	Date	Departure date.
`number_of_guests`	Integer	Total guest count.
`number_of_adults`	Integer	Adult count.
`number_of_children`	Integer	Child count.
`number_of_infants`	Integer	Infant count.
`number_of_teenagers`	Integer	Teenager count.
`number_of_juniors`	Integer	Junior count.
`number_of_seniors`	Integer	Senior count.
`arriving_guests`	JSON	Gender, name, and email of each arriving guest.
`booker`	JSON	Gender, name, and email of the booker.
`room_numbers`	JSON	Assigned room numbers.
`room_numbers_csv`	String	Room numbers as comma-separated string.
`room_types`	JSON	Room type codes.
`room_type_codes_csv`	String	Room type codes as comma-separated string.
`number_of_rooms`	Integer	Number of rooms reserved.
`total_before_tax`	Decimal	Total reservation price before tax.
`total_after_tax`	Decimal	Total reservation price after tax.
`prices`	JSON	Per-night prices.
`rate_plans`	JSON	Rate plan information.
`rates`	JSON	Rate details.
`hotel_name`	String	Hotel name.
`comments`	JSON	Room comments from the reservation.
`market_code`	String	Market code from the room stay.
`source_of_business`	String	Source of business.
`reservation_codes`	JSON	Reservation codes.
`reservation_code_names_csv`	String	Reservation code names as CSV.
`reservation_code_types_csv`	String	Reservation code types as CSV.
`gender`	String	Guest gender (`m` / `f`).