Skip to content

About

Email Markup

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Email Markup (com.skvare.emailmarkup)

Adds schema.org JSON-LD markup to CiviCRM's event emails, so Gmail shows them as event cards with a calendar entry and a check-in QR code. A cancellation updates the same card instead of leaving a stale one.

The visible email does not change: admins keep editing message templates as before. The extension only adds a <script type="application/ld+json"> block to the HTML part of these system workflow emails:

Workflow Markup
event_online_receipt EventReservation, Confirmed or Pending
event_offline_receipt EventReservation, Confirmed or Pending
participant_cancelled EventReservation, Cancelled

CiviMail bulk mailings never get markup.

This is an extension for CiviCRM, licensed under AGPL-3.0.

Getting started

  1. Install the extension. Markup ships switched off.
  2. Go to Administer > System Settings > Email Markup Settings and set the reservation prefix and ticket code. Do not change the prefix once markup is live: Gmail treats a new number as a new reservation.
  3. Go to Administer > System Settings > Email Markup Preview, enter a participant ID and check the JSON-LD and the sample email. Use Copy HTML to paste it into Google's Email Markup Tester.
  4. Use Send self-test to send the sample from the event's From address to that same address. Gmail shows markup from an unregistered sender only when sender and recipient are the same, so this needs access to that mailbox.
  5. Register the sending domain with Google (DKIM or SPF, DMARC, a dedicated transactional From address, and steady volume to Gmail).
  6. After Google approves the domain, switch on Add Gmail markup to emails.

Each event has a Gmail markup field on its Info and Settings tab, Add Gmail markup to confirmations: leave it empty to use the site default, or set it to No to exclude one event.

Google's Email Markup Tester also recommends two optional fields, and the preview page lists any that are missing:

  • performer: contacts registered for the event with the Speaker role, else your organization (the domain contact).
  • modifyReservationUrl: CiviCRM's self-service transfer/cancel page, so it is included only when the event has Allow self-service cancellation or transfer enabled and the participant can still use it (status and time limit).

See docs/README.md for mockups of how Gmail can show these emails, and real sample emails to paste into the Email Markup Tester.

When markup is skipped

The email is always sent; only the markup is left out when:

  • the master switch is off, the workflow is not selected, or the event's toggle is off;
  • the CiviCRM environment is not Production, so test sites never create real calendar entries;
  • the event hides its location, or has no address (online events);
  • the generated markup fails validation, for example a missing start date or an end date before the start.

Problems are logged to the emailmarkup log channel. Turn on Log every payload to log each payload and skip reason as well.

How it works

Civi\EmailMarkup\MailSubscriber listens to hook_civicrm_alterMailParams in the singleEmail context, where the rendered HTML is available. It reads the participant and event IDs from tokenContext, builds the reservation from a single API4 Participant.get (Builder\EventReservationBuilder), validates it (Validator) and inserts it before </body> (Injector). Generator runs the same steps for real sends and for the preview page. Any exception is caught and logged, so a markup problem never blocks a confirmation email.

Event dates use the site timezone. CiviCRM stores event times as local wall-clock times; the per-event timezone column from 5.47 was rolled back.

Tests

# Pure unit tests (no database)
phpunit --exclude-group headless

# Everything, including end-to-end sendTemplate() tests on the headless test database
CIVICRM_UF=UnitTests phpunit

Known issues and next phases

  • On CiviCRM 6.16 to 6.19, rendering an event email logs one PHP warning, Undefined array key "emailmarkup_event.add_markup:label". This is a core bug in CRM_Event_Tokens that affects every Yes/No or contact-reference custom field on Event; the email is unaffected. It is fixed in 6.20 by civicrm-core commit e2c412db65, which can be applied as a patch to earlier versions.
  • Phase 2: contribution and membership receipts as Order, participant transfers, and a setting to map custom participant statuses (they are sent as Pending for now).
  • Phase 3: scheduled reminders, RSVP for free-event invitations, and an .ics attachment and visible QR code for domains that are not registered with Google.

About

Email Markup

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages