Mailgun

Log into your Mailgun account at app.mailgun.com (or eu.mailgun.com if you signed up for the EU region). Navigate to Settings → API Keys in the left sidebar. You will see two types of keys: - **Private API Key** — starts with `key-`, used for server-side API calls. This is the key you will use in Bubble. Copy it now. - **Public Validation Key** — starts with `pubkey-`, used only for client-side email validation widgets. Do NOT use this in Bubble's API Connector. Now identify your region. Look at the URL in your browser: - If it shows `app.mailgun.com` — you are on the US region. Use base URL: `https://api.mailgun.net/v3` - If it shows `eu.mailgun.com` — you are on the EU region. Use base URL: `https://api.eu.mailgun.net/v3` Store your Private API Key securely. If it is ever exposed, go to Settings → API Keys → click the trash icon next to it to delete it and generate a new key immediately. Old API calls using the deleted key will fail within seconds. Also note your sending domain. Go to Sending → Domains in Mailgun. Your domain might be a custom domain you added (mg.yourdomain.com) or Mailgun's sandbox domain (sandboxXXXXX.mailgun.org) if you have not added a custom domain yet. The sandbox domain only sends to authorized recipients — for production you need a verified custom domain.

1// Mailgun credentials checklist:
2// Private API Key: key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  (Settings → API Keys)
3//   → This is the password in Basic Auth
4//   → Keep it Private
5//
6// Region:
7//   US: app.mailgun.com  → base URL: https://api.mailgun.net/v3
8//   EU: eu.mailgun.com   → base URL: https://api.eu.mailgun.net/v3
9//
10// Sending domain:
11//   Production: mg.yourdomain.com (must be verified)
12//   Testing: sandboxXXXXX.mailgun.org (verified emails only)

Before Mailgun can send emails on your behalf, your domain must be verified with DNS records. This proves to Mailgun (and receiving mail servers) that you own the domain. Sandbox domains are pre-verified but restricted to authorized recipients — for production, you need a custom domain. In Mailgun, go to Sending → Domains → Add New Domain. Enter your sending subdomain — the best practice is to use a subdomain like `mg.yourdomain.com` (not the root domain) so that email settings do not conflict with your root domain's existing MX records. Mailgun shows you the DNS records to add: - **TXT record for SPF**: proves Mailgun is authorized to send from your domain - **TXT record for DKIM**: a cryptographic signature for email authentication - **MX records**: required only if you want Mailgun to receive inbound emails on this domain (optional for outbound-only setups) - **CNAME record for tracking**: enables Mailgun's open and click tracking Log into your domain registrar's DNS settings (GoDaddy, Namecheap, Cloudflare, etc.) and add these records exactly as shown by Mailgun. DNS propagation takes between 5 minutes (Cloudflare) and 24–48 hours (some registrars). In Mailgun, click 'Verify DNS Settings' to check. The status should change from 'Unverified' to 'Active.' Until your domain shows 'Active' status, any send attempts to that domain will fail with a 'Domain not found' or 'Unauthorized' error.

1// DNS records to add for mg.yourdomain.com in Mailgun:
2// (values shown as examples — use the exact values from Mailgun's UI)
3
4// SPF (TXT record):
5// Name: mg.yourdomain.com
6// Value: v=spf1 include:mailgun.org ~all
7
8// DKIM (TXT record):
9// Name: mailo._domainkey.mg.yourdomain.com
10// Value: k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQK...
11
12// Tracking CNAME (optional but recommended for click/open tracking):
13// Name: email.mg.yourdomain.com
14// Value: mailgun.org

In your Bubble editor, click 'Plugins' → 'API Connector.' Click 'Add another API' and name it 'Mailgun.' Click 'Add another call' and name it 'Send Email.' Set the method to POST. For the URL, use your region-specific endpoint with your domain: - US: `https://api.mailgun.net/v3/mg.yourdomain.com/messages` - EU: `https://api.eu.mailgun.net/v3/mg.yourdomain.com/messages` Replace `mg.yourdomain.com` with your actual verified Mailgun sending domain. Set up authentication: click the authentication dropdown and select 'Basic auth.' In the Username field, type exactly: `api` — that is the literal string 'api', nothing more. In the Password field, paste your Mailgun Private API Key (key-xxx). Check 'Private' on both fields. CRITICAL: Change the body type to 'Form data' (not JSON body). Mailgun's `/messages` endpoint requires `application/x-www-form-urlencoded` encoding. JSON body returns a 400 error. Add the following form-data body fields: - `from` — the sender address, format: `Name <email@mg.yourdomain.com>`. Mark it with a default value or make it dynamic. The email address must be on your verified Mailgun domain. - `to` — the recipient email address (dynamic) - `subject` — the email subject line (dynamic) - `text` — plain text version of the email (dynamic; provide at least this or `html`) - `html` — HTML version of the email (optional but recommended for branded emails; dynamic) Click 'Initialize call.' Enter real values for from, to (use your own email), subject, and text, then click Initialize. You should receive a test email within a few minutes.

1// API Connector: Mailgun → Send Email
2// Method: POST
3// URL: https://api.mailgun.net/v3/mg.yourdomain.com/messages
4//      (or https://api.eu.mailgun.net/v3/mg.yourdomain.com/messages for EU)
5//
6// Authentication: Basic Auth
7//   Username: api         // literal string 'api' — NOT your email — mark Private
8//   Password: key-xxxx   // Mailgun Private API Key — mark Private
9//
10// Body type: Form data (NOT JSON)
11// Form fields:
12//   from:    Sender Name <noreply@mg.yourdomain.com>   (can be static default)
13//   to:      <dynamic_recipient_email>
14//   subject: <dynamic_subject_line>
15//   text:    <dynamic_plain_text_body>
16//   html:    <dynamic_html_body>  (optional — for branded emails)

Wire the Mailgun API Connector call to real Bubble workflow events. The pattern is: a triggering event fires a workflow that calls the Mailgun Send Email action. For secure server-side execution, wrap the Mailgun action in a Backend Workflow (Bubble paid plan). This ensures your API Key stays completely server-side and the email is sent even if the user navigates away. Trigger the Backend Workflow from client-side actions using 'Schedule API Workflow' at 'Current date/time.' Common email scenarios: **Order confirmation**: Trigger: When an Order record is created → Backend Workflow → Send Email - from: `Acme Shop <orders@mg.yourdomain.com>` - to: Order's customer_email - subject: `Your order #` + Order's order_number + ` is confirmed!` - text: `Hi ` + Order's customer_name + `, thank you for your order. Total: $` + Order's total_amount - html: Build an HTML template with Bubble's text formatting, wrapping the dynamic values in styled HTML **Welcome email**: Trigger: When a User record is created → Backend Workflow → Send Email - to: New User's email - subject: `Welcome to [App Name]!` **Password reset / email verification**: Generate a unique token, store in the User record with expiry, build a verification URL containing the token as a URL parameter, and include the URL in the email body. For bulk sends (e.g., newsletter to a list of users), use Mailgun's batch sending with recipient variables rather than looping through users in Bubble with a 'Do a search for' each. Looping sends individual API calls — one per user — which burns WU unnecessarily. Mailgun's batch send accepts a `to` field with multiple addresses and a JSON `recipient-variables` parameter for personalizing each email.

1// Backend Workflow: Send Order Confirmation Email
2// Trigger: When Order is created
3// Step 1: Plugins → Mailgun → Send Email
4//   from: "Acme Shop <orders@mg.yourdomain.com>"
5//   to:   Order's customer_email
6//   subject: "Order #" + Order's order_number + " Confirmed"
7//   text: "Hi " + Order's customer_name + ",\n\nThank you for your order.\nTotal: $" + Order's total_amount + "\n\nWe'll notify you when it ships."
8//   html: "<h1>Order Confirmed</h1><p>Hi " + Order's customer_name + "</p>..."
9
10// Email verification workflow:
11// Step 1: Set User's email_token = Generate random string (length 32)
12// Step 2: Set User's email_token_expires = Current date/time + 86400 seconds
13// Step 3: Backend Workflow → Send Email
14//   subject: "Verify your email address"
15//   text: "Click to verify: https://yourapp.bubbleapps.io/verify?token=" + User's email_token

Mailgun can notify your Bubble app when emails are delivered, opened, clicked, bounced, or marked as spam. This is essential for maintaining email list hygiene — sending repeatedly to bounced addresses damages your sender reputation and wastes API calls. For inbound Mailgun events, you need a Bubble paid plan for Backend Workflows. In Bubble, go to Settings → API → check 'This app exposes a Workflow API.' Copy your workflow API base URL. In Backend Workflows, create a new workflow named `mailgun_events`. Click 'Detect data' and Bubble listens for the next incoming request. In Mailgun Dashboard, go to Sending → Webhooks. Click 'Add webhook.' Select the event types you want to track (Delivered, Permanent Failure/Bounced, Spam Complaint, Unsubscribed). Enter your Bubble workflow URL: `https://appname.bubbleapps.io/api/1.1/wf/mailgun_events`. Mailgun sends a test request when you save the webhook — Bubble's Detect Data captures the schema. Mailgun's webhook payload is a JSON POST with a nested structure: the event data lives inside `event-data` → all fields are under this parent key. Key fields to detect and use: - `event-data.event` — event type: 'delivered', 'failed', 'complained', 'unsubscribed' - `event-data.recipient` — the recipient email address - `event-data.timestamp` — Unix timestamp of the event - For failed events: `event-data.reason` — bounce reason, `event-data['delivery-status'].code` — SMTP code In the Backend Workflow actions: 1. Find the User record where email = Step 1's event-data.recipient 2. If event = 'failed' (permanent bounce): Set User's email_valid = 'no' 3. Create an Email_Event record logging the event type, recipient, and timestamp 4. Return HTTP 200 with `{"status": "received"}` to acknowledge the webhook RapidDev has built email delivery tracking systems for multiple Bubble clients — if you need complex bounce handling with suppression management, book a free consultation at rapidevelopers.com/contact.

1// Mailgun webhook POST body structure (JSON):
2{
3  "event-data": {
4    "event": "failed",
5    "timestamp": 1735900000,
6    "recipient": "user@example.com",
7    "message": {
8      "headers": {
9        "message-id": "<msg-id@mg.yourdomain.com>"
10      }
11    },
12    "reason": "bounce",
13    "delivery-status": {
14      "code": 550,
15      "message": "5.1.1 The email account does not exist"
16    },
17    "flags": {
18      "is-test-mode": false,
19      "is-routed": false
20    }
21  }
22}
23
24// Bubble Backend Workflow detected fields:
25// event-data.event         → text (delivered, failed, complained, unsubscribed)
26// event-data.recipient     → text
27// event-data.timestamp     → number (Unix)
28// event-data.reason        → text (for failed events)
29// event-data.delivery-status.code → number

Sending emails to addresses that have previously bounced harms your deliverability. Mailgun maintains a suppression list — a database of bounced and unsubscribed addresses for your domain. Before sending important emails, check whether the recipient is on the suppression list. Add a second API Connector call in Bubble named 'Check Email Suppression.' Set the method to GET and the URL to: `https://api.mailgun.net/v3/mg.yourdomain.com/bounces/{{email_address}}` Use the same Basic Auth credentials (username: 'api', password: your Private API Key, both Private). Make `email_address` a dynamic parameter. Mailgun returns HTTP 200 if the address is on the bounce list, and HTTP 404 if it is NOT on the bounce list (meaning it is safe to send). This inverse logic can confuse developers — a 404 response means 'not found in bounces = safe to email.' In a Bubble workflow, handle this by: 1. Call the Check Suppression API Connector action 2. If the response status is 404 (not in bounces), proceed to send the email 3. If the response returns a bounce record (200), skip sending and mark the email as invalid in the database Bubble's API Connector handles HTTP 404 responses as errors — check the workflow's error step to capture 404s and treat them as the 'safe to send' signal. For better performance, cache this check: once you verify an email is not bounced, flag it as `email_verified: yes` in your Bubble User record and skip the suppression check for subsequent sends. Re-check only when a new bounce webhook arrives.

1// API Connector: Mailgun → Check Email Suppression
2// Method: GET
3// URL: https://api.mailgun.net/v3/mg.yourdomain.com/bounces/{{email_address}}
4// Authentication: Basic Auth → username: api, password: key-xxx (Private)
5
6// Response logic:
7// HTTP 200 → address IS on bounce list → do NOT send email
8// HTTP 404 → address is NOT on bounce list → safe to send
9
10// Bubble workflow:
11// Step 1: Call Check Email Suppression with recipient email
12// Step 2: If Step 1 returned data (200 - found in bounces):
13//   → Set User's email_valid = 'no'
14//   → End workflow (skip send)
15// Step 3 (on Step 1 error / 404):
16//   → Continue to Send Email action