Skip to main content

Portal-Mailgun

Portal guide to connect a Mailgun account, manage email templates and set a custom subject for guest access emails

Written by QA

1. What You Need Before Connecting Mailgun

To connect Mailgun successfully, make sure you have:

  • Access to Apps tab in Portal and search for Mailgun

  • A Mailgun account

    • Starter or Standard plan for custom domains

    • The free plan can only send to manually verified recipients

  • A verified Mailgun sending domain

    • SPF and DKIM are correctly set up

  • An authorized From address

  • Your:

    • Mailgun API Key

    • Webhook Signing Key

    • Account / Domain details
      ​

2. Enable Email Notifications in Portal

Before connecting Mailgun:

  1. Go to Settings → Customization → Key Notifications

  2. Ensure Email is enabled

If Email is disabled here, automatic emails will not be sent.

3. Open the Mailgun App

You can access Mailgun in two ways:

  • Go to the Apps tab and search for Mailgun

4. Configure Mailgun

  1. In Apps → Mailgun, click Connect

  2. Enter:

    • Account / Domain information

    • API Key

    • Webhook Signing Key

  3. Click Save to connect

Expected Result

  • If credentials are valid → integration saves successfully

  • If credentials are invalid → error message appears and integration is not saved

5. Custom Email Subject

If your property sends guest emails through its own Mailgun account, you can write your own subject line for the "Access is ready" email. This is the email guests receive with their access details.

A custom subject helps the email match your property's voice and makes it easier for guests to recognise it in their inbox. You set one subject, and it's used for both the styled and the plain version of the email.

Good to know: Custom subjects only work while your Mailgun connection is active. If it is deactivated or disconnected, guests receive the email with Portal's default subject.

Setting a custom subject

  1. Go to Apps and open the Mailgun app.

  2. Open the Templates tab. You'll see the Access is ready card, with the email subject at the top and the Styled email and Plain email template choices below it.

  3. Type your subject in the Email subject field. When the field is empty, it shows the current default subject as a hint.

  4. Click Save changes in the bar at the bottom of the page.

The next "Access is ready" email will use your new subject.

Adding guest and booking details

You can add details such as the guest's first name or your property name to the subject. Portal fills them in for each guest.

  • Click the Variable button and pick from the searchable list. Variables are grouped into Guest, Booking and Property, and each one shows a sample value.

  • Or type {{ in the subject field to open the same list.

Example: Your access to {{propertyName}} is ready, {{firstName}}

Previewing the subject

While you edit, an inbox preview shows how the subject will look. You can switch between two views:

  • Sample guest: every detail is filled in with sample values.

  • Missing details: a guest who has none of the optional details. Only the property name is filled in.

Check the "Missing details" preview. If a guest doesn't have a value, for example no first name, that part is left empty and extra spaces are removed. Punctuation around it stays. So "Your access is ready, {{firstName}}" becomes "Your access is ready," with a trailing comma. Write your subject so it still reads well when a detail is missing.

When your subject uses any variable other than the property name, a note reminds you that missing values are left empty.

Subject rules

  • Up to 150 characters. A counter next to the field shows how many you've used.

  • Only variables from the list. A variable that isn't on the list, or an unfinished {{, is highlighted on the field.

  • The App Link variable can't be used in the subject.

If the subject breaks one of these rules, the problem is shown on the field and you can't save until it's fixed.

Saving and discarding changes

The Save changes bar saves your subject and your template choices together in one step. Discard undoes all unsaved changes.

A badge next to the field shows the subject's status: Default, Custom or Unsaved.

Going back to the default subject

Either clear the subject field or click Reset to default, then click Save changes. The next email will use Portal's default subject.

7. Sending Emails via Mailgun

When Mailgun is connected and templates are synced:

  • Portal sends emails using your Mailgun domain

  • Branding and From address come from Mailgun

  • Emails are sent when:

    • A Key is created

    • Access is generated

    • Credentials are issued

Delivery Timing

  • Allow up to ~1 minute

  • Timestamps follow the Portal timezone

8. Fallback Email Behavior

If Mailgun is not connected:

  • Portal automatically uses its default mailing service

  • Emails are still sent

If a template is deleted in Mailgun:

  • Portal continues sending emails

  • System falls back to the default system template

  • On the first failed send attempt, the system sends a notification to inform staff about the template issue.

Deleting a template in Mailgun does not break email delivery.

9. Customisation vs Manual Sharing (Important)

Email Disabled in Customisation

  • Automatic emails are not sent

  • Applies to:

    • Key creation

    • PMS-based flows

    • Automatic credential delivery

Manual Share Overrides Disable

When staff manually share credentials from Key Details:

  • Email is always sent

  • Even if Email is disabled in Customisation

Template used:

  • Property template (if exists)

  • Otherwise, default system template

10. Edge Cases & Errors

Invalid API or Webhook Key

  • Integration fails to save

  • Re-enter the correct keys

Free Mailgun Plan

  • Can only send to manually verified recipients

  • Custom domain sending requires Starter or Standard

Template Mismatch

  • Sync fails

  • Variables render incorrectly

  • Fix names and variables exactly as shown in Portal

Rotated or Revoked Keys

  • Integration breaks

  • Update keys in Apps → Mailgun

11. Troubleshooting Checklist

Emails Not Arriving

  • Confirm Email is enabled in Customisation

  • Check Apps → Mailgun connection

  • Verify SPF/DKIM

  • Ensure templates show Synced and Ready to Use

  • Check the spam folder

  • Review Mailgun logs

  • Allow ~1 minute

Templates Not Syncing

  • Names must match exactly

  • Variables must be case-sensitive

  • Click Check All Templates after changes

Need to Email Guests on Free Plan

  • Upgrade to Starter or Standard

  • Verify sending domain

12. Security Best Practices

  • Treat API & Webhook keys like passwords

  • Rotate keys regularly

  • Restrict access to Apps → Mailgun

  • Never share keys in chats or screenshots

FAQs

Q: Which templates are supported?
A: Access is ready, in its Styled email and Plain email versions

Q: Where do I find template variables?
A: In Portal’s Apps tab>Mailgun> Template tab (case-sensitive)

Q: Which emails use the custom subject?
A: The "Access is ready" email, in both its styled and plain versions. The data access link email is sent the same way, so it uses this subject too.

Q: What happens to my custom subject if I disconnect Mailgun?
A: Your custom subject is removed and emails go out with the default subject. If you reconnect later, you'll need to set the subject again.

Q: Can I set the subject on my phone?
A: Yes. The Templates tab works at mobile width: the variable list opens from the bottom of the screen, and the Save changes bar stays at the bottom.

Q: When are emails sent?
A: As soon as a Key is issued and access is generated

Q: What if Mailgun is not connected?
A: Portal uses its default mailing service

Q: Can I use different From addresses per property?
A: Yes, using separate verified Mailgun domains per property

Related Articles

Did this answer your question?