Mailgun Integration

Overview

Mailgun is used for all transactional email delivery — welcome emails, viewing request notifications to agents, bills communications, and more.

File: api/utils/sendEmail.php

Configuration

Mailgun is configured per region with separate API keys and domains:


function sendEmail($to, $subject, $body, $replyToName = '', $replyToEmail = '', $bcc = '', $attachment = '')
{
    $USA = json_decode($_ENV['USA']);
 
    $mgClient = $USA
        ? Mailgun::create('...us-key...')
        : Mailgun::create('...uk-key...', 'https://api.eu.mailgun.net/v3/mg.housr.co.uk');
 
    $domain = $USA ? "mg.us.housr.com" : "mg.housr.co.uk";
 
    $params = [
        'from' => $USA ? 'Housr <noreply@mg.us.housr.com>' : 'Housr <noreply@housr.co.uk>',
        'to' => $to,
        'bcc' => $bcc,
        'subject' => $subject,
        'html' => $body
    ];
}

Regional Settings

Setting	UK	US
API Endpoint	`https://api.eu.mailgun.net/v3/mg.housr.co.uk` (EU)	Default (US)
Domain	`mg.housr.co.uk`	`mg.us.housr.com`
From Address	`Housr <noreply@housr.co.uk>`	`Housr <noreply@mg.us.housr.com>`

Features

Reply-To Headers

When provided, sets custom reply-to for emails (e.g., student’s email on viewing enquiries):


if ($replyToName != '' && $replyToEmail != '') {
    $params['h:reply-to'] = $replyToName . ' <' . $replyToEmail . '>';
}

Attachments

Supports file attachments (e.g., proof of address letters):


if ($attachment != '' && file_exists($attachment)) {
    $params['attachment'] = [
        ['filePath' => realpath($attachment), 'filename' => basename($attachment)]
    ];
}

BCC

Supports BCC recipients for monitoring/audit purposes.

Email Templates

HTML email templates are stored in api/include/:

Directory	Purpose
`include/new-welcome-email/`	Welcome email on signup
`include/bills_welcome_2025/`	Bills welcome email
`include/website-bills/`	Website bills email templates
`include/website-enquiry-responses/`	Website enquiry response templates
`include/uk/`	UK-specific email templates (enquiry_request.html, information_request.html, bookingAcceptedConfirmationAgentEmail.html)
`include/us/`	US-specific email templates (enquiry_request.html, bookingAcceptedConfirmationAgentEmail.html)

Templates use placeholder replacement:


$emailBody = file_get_contents('./include/uk/enquiry_request.html');
$emailBody = str_replace('[ADDRESS]', $address, $emailBody);
$emailBody = str_replace('[BOOKING_NAME]', $username, $emailBody);
$emailBody = str_replace('[NUMBER]', $contactno, $emailBody);
$emailBody = str_replace('[EMAIL]', $email, $emailBody);

Usage Contexts

Context	Template	Triggered By
Welcome Email	`new-welcome-email/index.html`	`signup.php`
Viewing Enquiry (UK)	`uk/enquiry_request.html`	`requestViewing.php`
Viewing Enquiry (US)	`us/enquiry_request.html`	`requestViewing.php`
Information Request (UK)	`uk/information_request.html`	`requestViewing.php` (request_type=INFORMATION)
Booking Confirmation	`uk/bookingAcceptedConfirmationAgentEmail.html` or `us/` variant	`requestViewing.php` (slot booking)
Bills Welcome	`bills_welcome_2025/`	Bills signup flow
Proof of Address	Generated PDF attachment	`proofOfAddressLetter.php`

Helper Function

getStudentsHtml($link, $roomId) generates an HTML table of student names for a chat room, used in contract-related emails.

Dependencies


"mailgun/mailgun-php": "~3.0.0"

Note: PHPMailer is also available (api/PHPMailer/) as an alternative for specific use cases, but Mailgun is the primary email service.