Black Friday
Skip to documentation content

Developer Reference

Use the Email Customization Contract

Use the Free email presentation API, filters, layout providers and protected slots, with Pro profile precedence, fallback diagnostics and queue behavior.

Email Customization Contract 1.0.0 is the public presentation boundary for booking emails in KimoraPro Hotel Booking Free 3.30.0. It supports developer customization from a site plugin independently of the active theme. Pro 1.38.0 adds the administrator editor on the same contract.

For the administrator workflow, see Customize booking email content and branding.

Choose the owning layer

  • Core Free: email catalog, view data, placeholders, protected slots, default layout, rendering and fallback.
  • Hotel Booking Pro: administrator profiles, shared design, drafts, apply/history, preview/test controls and policy contributions.
  • Site plugin: developer layout registration and presentation filters.
  • Theme: website presentation. Email templates remain outside the Theme Contract and its template-override catalog.

Do not edit Core or Pro email view files or place persistent email overrides in a theme. The contract changes presentation only: recipients, saved locales, booking/payment state, security URLs, entitlements, scheduling, queue deduplication, privacy suppression and attachments retain their owning workflows.

Detect the contract and inspect the API

Check function_exists('kimorapro_hb_email_customization_contract_version') and the returned compatible major version before calling the facade. The corresponding constant is KIMORAPRO_HB_EMAIL_CUSTOMIZATION_CONTRACT_VERSION. The public manifest is email-customization-contract.json.

kimorapro_hb_email_customization() returns a read-only facade with contractVersion(), catalog(), layouts(), activeLayout($type, $locale), validate($type, $content, $branding), defaults($type, $locale), preview($type, $locale, $scenario, $profile, $purpose), render($data, $options) and diagnostics(). Query the catalog for supported fields, tokens and email types instead of maintaining a separate catalog.

Preview/test rendering uses synthetic data and does not create bookings, invoices, access/review tokens, outbox rows or mail. The facade’s render method accepts preview/test purposes only. Live rendering belongs to the notification queue; sending a test email is a separate Pro editor operation.

Customize wording from a site plugin

The kimorapro_hb_email_view_data filter receives an array of view data and a read-only context. Only changes to content.* and branding.* are accepted. For example, a site plugin can change the greeting:

add_filter('kimorapro_hb_email_view_data', static function (array $data, array $context): array {
    $data['content']['greeting'] = 'Hello {{guest.name}},';
    return $data;
}, 10, 2);

Content fields are subject, headline, greeting, intro, cta_label and footer. Branding fields are logo_url, logo_alt, background_color, header_color and accent_color. Validate supported values and lengths through the facade. HTML fragments allow paragraphs, line breaks, emphasis, underline, lists and links using http, https or mailto; they do not accept arbitrary HTML/CSS or placeholders in attributes.

Supported placeholders are {{hotel.name}}, {{guest.name}}, {{booking.code}}, {{stay.check_in}} and {{stay.check_out}}. The context exposes contract, notification type, audience, locale, HTML language, direction and purpose. Attempts to change context, protected sections or resolved tokens through the view-data filter are ignored.

Public registration and rendering hooks

  • kimorapro_hb_email_customization_register — action receiving the registry; register a layout with registerLayout(array $definition).
  • kimorapro_hb_email_template — filter receiving the layout ID and context; return a registered layout ID, an empty string or core. File paths are not accepted.
  • kimorapro_hb_email_view_data — filter receiving the view-data array and context; edit declared content and branding only.
  • kimorapro_hb_email_slot_contributions — filter receiving HTML contributions, slot name and slot context; supports room_policies and cancellation_policy. Contributions are sanitized. The slot context includes a booking ID for live rendering and zero for preview/test.

Register a layout provider

A layout definition requires id, requires_contract, root, template, supports.content, supports.branding and slots. Optional entries include label, version, supported email types and defaults. Use a compatible contract major that is no newer than the installed contract.

The template must be a relative PHP file inside a trusted plugin or must-use-plugin root. Upload directories, path traversal and symlink escapes are rejected. Declare every content/branding field the layout actually renders; the Pro editor treats undeclared fields as managed by the developer layout.

The template receives $email, an EmailTemplateContext. Use its context-safe accessors, including text(), html(), block(), color(), logo() and slot(), rather than reading a Booking object or outputting unescaped values.

Render each required slot exactly once: notice, details, room_policies, action and cancellation_policy. Empty slot wrappers count. The support slot is also available. Use $email->slot('details') and the equivalent calls for the other slots so the protected markers and content are retained.

Resolution, fallback and diagnostics

Content resolves in this order: Core defaults → declared provider defaults → view-data filter → applied Pro administrator profile (or the explicit preview/test draft) → placeholder substitution. Administrator choices are applied after filters. A provider’s unsupported fields are reported and are not applied.

If a requested provider is rejected or missing, its template throws, required slots are absent or repeated, or the output fails validation, Core uses the default layout with the same resolved content. Inspect layouts(), activeLayout() and diagnostics(); the Pro Templates page also displays developer-layout diagnostics.

Queue behavior and scope

Subject, body and language locale are rendered before enqueueing. Retries reuse that stored content. Applying a profile, changing a filter or updating a layout affects newly generated messages and does not rewrite queued or sent messages.

The catalog covers thirteen guest/staff booking emails. Pro reminders and review requests still require their sending features; customization creates no trigger and enables no disabled notification. Welcome, password-reset, Contact, Newsletter and other WordPress/WooCommerce emails are outside this contract. The PDF invoice document has its own workflow.

Keep persistent customizations in a site plugin and verify the relevant email types, locales, preview situations and fallback paths in a test environment before deploying that plugin. Continue with the administrator guide and booking email and invoice verification.

Was this article helpful?

Your feedback helps us improve the documentation.