Connect Mailgun: High-Throughput Developer Email API

​

Overview

​

Architecture and Dispatch Sequence

​

Step 1: Obtain Credentials from Mailgun

1. Log into your Mailgun dashboard at app.mailgun.com.
2. Navigate to Sending -> Domains and add your sending subdomain (e.g. mail.skylinerealty.com).
3. Add the two TXT records (SPF and DKIM k=rsa; p=...) and MX routing records provided by Mailgun into your DNS management console.
4. Navigate to Settings -> API Security and copy your primary Private API Key (starting with key-).
5. Note your account region (US or EU).

​

Step 2: Connect in the BrokerOS Web Dashboard

1. Navigate to Dashboard -> Marketing -> Email -> Settings.
2. Select the Providers & Domains tab (/dashboard/marketing/email/settings?tab=providers).
3. Click Add Provider and choose Mailgun.
4. Fill in the modal connection fields:

5. Click Verify & Connect. BrokerOS connects to GET /v3/domains/{domain}, verifies active domain status, encrypts the credentials via AES-256-GCM, and stores them in MarketingIntegration.

​

Step 3: Configure Webhook Endpoints in Mailgun

1. In Mailgun, go to Sending -> Webhooks.
2. Add your BrokerOS webhook destination URL:
   https://api.yourfirm.com/api/marketing/email/webhooks/mailgun
   
3. Enable events for Delivered Messages, Permanent Failure, Temporary Failure, Clicks, Opens, and Unsubscribes.
4. Save the webhook. BrokerOS MailgunWebhookParser processes incoming callbacks automatically.

​

Webhook Event Telemetry Mapping

​

Integration Implementation Details

​

Multi-Region Resolution

export class MailgunClient {
  private apiKey: string;
  private domain: string;
  private region: 'US' | 'EU';

  constructor(credentials?: ProviderCredentials) {
    this.apiKey = credentials?.apiKey || process.env.MAILGUN_API_KEY || '';
    this.domain = credentials?.mailgunDomain || process.env.MAILGUN_DOMAIN || '';
    this.region = (credentials?.mailgunRegion as 'US' | 'EU') || 'US';
  }

  private getBaseUrl(): string {
    return this.region === 'EU' ? 'https://api.eu.mailgun.net/v3' : 'https://api.mailgun.net/v3';
  }

  private getAuthHeader(): string {
    const auth = Buffer.from(`api:${this.apiKey}`).toString('base64');
    return `Basic ${auth}`;
  }
}

​

Form-Encoded Dispatch

const params = new URLSearchParams();
params.append('from', `"${options.fromName}" <${options.fromEmail}>`);
recipientEmails.forEach((to) => params.append('to', to));
params.append('subject', options.subject);
params.append('html', options.htmlContent);

if (options.plainTextContent) {
  params.append('text', options.plainTextContent);
}

if (options.replyTo) {
  params.append('h:Reply-To', options.replyTo);
}

if (options.tracking) {
  params.append('o:tracking', 'yes');
  params.append('o:tracking-clicks', options.tracking.enableClicks ? 'yes' : 'no');
  params.append('o:tracking-opens', options.tracking.enableOpens ? 'yes' : 'no');
  if (options.tracking.campaignId) {
    params.append('v:campaignId', options.tracking.campaignId);
  }
}