> ## Documentation Index
> Fetch the complete documentation index at: https://flexforms.bjanczak.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Write for Filament/Laravel developers buying Flex Forms.
> Be precise: every setting documents what it does and how it works.
> Use Help Center components richly: Steps, Cards, Callouts, Tabs, CodeGroup, Mermaid, Badge for Pro.
> Never invent APIs; match the real Flex Forms package behavior.

# Mailgun Integration

> A comprehensive guide to overriding standard SMTP and sending robust, high-deliverability transactional emails directly through the Mailgun API.

<Banner type="info" dismissible={false}>
  📚 **Developer Reference:** To deeply understand how the API overrides SMTP and structures the message payloads, please read the [Official Mailgun API Documentation](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/messages).
</Banner>

The **Mailgun** integration is an enterprise-grade transport layer that completely bypasses your server's standard, often unreliable SMTP configuration. By connecting Flex Forms directly to the Mailgun API, you guarantee lightning-fast delivery for critical transactional emails, such as autoresponders, submitter receipts, and internal administrative alerts.

## Enterprise Business Use Cases

<CardGroup cols={2}>
  <Card title="Bulletproof Deliverability" icon="shield-check">
    Standard PHP SMTP can often be flagged as spam or suffer from severe rate limits on shared hosting. The Mailgun API integration ensures your critical "Thank You for Contacting Us" receipts actually land in the primary inbox, instantly.
  </Card>

  <Card title="High-Volume Routing" icon="route">
    If your form receives thousands of submissions per hour, standard SMTP queues will crash. The Mailgun API handles massive concurrency, effortlessly routing thousands of administrative notification emails simultaneously.
  </Card>
</CardGroup>

***

## Ultra-Detailed, Step-by-Step Setup Guide

Connecting Flex Forms to Mailgun requires generating a highly secure API Key and strictly defining your verified sending domain and geographical region. Follow these exact instructions.

<Steps>
  <Step title="Step 1: Log into Mailgun">
    Open your web browser and navigate to the Mailgun login portal. Enter your credentials to access the main administrative dashboard.
  </Step>

  <Step title="Step 2: Access the Sending Menu">
    Once logged in, look at the **left-hand sidebar navigation menu**. Locate the section labeled **Send** and expand it. Then, click exactly on the sub-menu link labeled **Sending**.
  </Step>

  <Step title="Step 3: Navigate to Domains">
    Under the "Sending" section, click exactly on **Domains**. You will now see a list of domains you have registered with Mailgun.

    *Note: You MUST have a fully verified domain (e.g., `mg.yourcompany.com`) with green checkmarks next to the DNS records before proceeding.*
  </Step>

  <Step title="Step 4: Select Your Verified Domain">
    Click directly on the verified domain name you intend to use for sending Flex Forms emails.
  </Step>

  <Step title="Step 5: Navigate to Domain Settings">
    You are now looking at the overview for that specific domain. Look at the sub-navigation tabs near the top of this specific page. Click exactly on **Domain settings**.
  </Step>

  <Step title="Step 6: Access Sending API Keys">
    In the "Domain settings" menu, locate and click on the tab labeled **Sending API keys**.
  </Step>

  <Step title="Step 7: Generate the API Key">
    Click the prominent button labeled **Add API key**.
    Mailgun will generate a highly secure, long string of alphanumeric characters.

    Highlight the entire string, right-click, and select **Copy** (or press `Ctrl+C` / `Cmd+C`). Make absolutely sure you do not highlight any blank spaces.
  </Step>

  <Step title="Step 8: Inject Credentials into Flex Forms">
    Switch to your Flex Forms administrative dashboard in a new tab.

    1. Open Integrations (Flex Forms left rail) → Mailgun.
    2. Paste the API Key you copied into the **API Key** input field.
    3. Enter the exact **Domain** you selected in Step 4 (e.g., `mg.yourcompany.com`) into the Domain field.
    4. Select your **Region** (US or EU). This tells Flex Forms whether to ping `api.mailgun.net` or `api.eu.mailgun.net`. If you select the wrong one, the API will fail instantly.
    5. Click the **Save Settings** button.
  </Step>
</Steps>

***

## Configuration & Masterclass Usage

Once Mailgun is authenticated and active, it silently takes over the email transport layer for all notifications generated by Flex Forms (such as the "Submitter Receipt" or "Admin Alert" emails configured in the Studio).

There is no field mapping required for Mailgun, as it simply acts as the delivery engine for emails formatted by Flex Forms.

### The Sender Authentication Trap

<Tree>
  <Tree.Folder name="Strict Sender Validation" defaultOpen>
    <Tree.File name="If you verified the domain: mg.yourcompany.com in Mailgun." />

    <Tree.File name="You configure a Flex Forms Admin Alert to send FROM: sales@yourcompany.com." />

    <Tree.File name="Mailgun intercepts the email." />

    <Tree.File name="Mailgun sees the FROM domain (yourcompany.com) DOES NOT match the verified domain (mg.yourcompany.com)." />

    <Tree.File name="Mailgun instantly DROPS the email and throws a 400 error." />
  </Tree.Folder>
</Tree>

<Callout type="warning">
  **CRITICAL SENDER RULE:** To guarantee delivery, the "From Address" configured in your Flex Forms Notification Settings in the Studio MUST exactly match the verified domain you configured in Mailgun. If your verified domain is a subdomain like `mg.yourcompany.com`, your From address MUST be something like `noreply@mg.yourcompany.com`.
</Callout>

***

## Troubleshooting & Enterprise FAQs

<AccordionGroup>
  <Accordion title="API Error: 401 Unauthorized">
    **The Problem:** The server logs show a `401 Unauthorized` error when attempting to send an email.

    **The Solution:** This almost always means the API Key you pasted in Step 8 is incorrect, or you selected the wrong Region (US vs EU). If your Mailgun account is hosted in Europe, but you set the Flex Forms region to US, the API will reject your key as invalid. Verify your region and re-paste the key.
  </Accordion>

  <Accordion title="API Error: Free accounts are restricted">
    **The Problem:** The server logs show an error stating "Free accounts are restricted to verified routing addresses."

    **The Solution:** If you are using a free Mailgun sandbox domain (e.g., `sandbox123.mailgun.org`), Mailgun strictly prohibits you from sending emails to anyone except yourself. You must upgrade to a paid Mailgun tier and verify a custom domain to send emails to your customers.
  </Accordion>
</AccordionGroup>

***

## Configuration Reference

The following advanced settings are available in the Flex Forms UI for this integration. Use this reference to understand exactly how each field impacts the API payload.

### Global Settings

Located in **Integrations** in the Flex Forms left rail.

<ParamField path="api_key" type="password" required>
  **Mailgun Private API Key**
  The master API key that allows Flex Forms to send emails through your Mailgun account. Do *not* use a public validation key.
</ParamField>

<ParamField path="region" type="select" default="us">
  **Region**
  Mailgun isolates EU data from US data. If you created your Mailgun account in Europe, you *must* select `EU` here, otherwise API requests will fail with a 401/404 error.
</ParamField>

<ParamField path="default_from_email" type="text">
  **Default from email**
  The fallback sender address (e.g., `noreply@mg.yourdomain.com`). **CRITICAL:** The domain in this email address *must* be exactly verified within your Mailgun account. Mailgun will permanently reject any emails sent from unverified domains.
</ParamField>

<ParamField path="default_from_name" type="text">
  **Default from name**
  The fallback sender name (e.g., `Flex Forms System`).
</ParamField>

### Form-Level Settings

Located on the form hub **Integrations** tab for a specific form.

#### Envelope & Addressing

<ParamField path="to" type="text" required>
  **To**
  The destination email address. You can provide a hardcoded email (e.g., `sales@example.com`) or use a merge tag to send the email directly to the person who filled out the form (e.g., `{{email_input}}`). Separate multiple addresses with commas.
</ParamField>

<ParamField path="from_email" type="text">
  **From email**
  Overrides the Global Default From Email for this specific form. Must still belong to a verified Mailgun domain.
</ParamField>

<ParamField path="from_name" type="text">
  **From name**
  Overrides the Global Default From Name.
</ParamField>

<ParamField path="reply_to" type="text">
  **Reply-To**
  When the recipient clicks "Reply" in their email client, their response will go here. *Highly recommended:* Set this to the user's email block (e.g., `{{email_input}}`) so your sales team can reply directly to the submitter.
</ParamField>

<ParamField path="cc" type="text">
  **CC**
  Carbon Copy addresses. Comma-separated.
</ParamField>

<ParamField path="bcc" type="text">
  **BCC**
  Blind Carbon Copy addresses. Comma-separated. Excellent for silent auditing.
</ParamField>

#### Email Content

<ParamField path="subject" type="text" required>
  **Subject**
  The subject line of the email. Supports merge tags (e.g., `New Lead: {{company_name}}`).
</ParamField>

<ParamField path="body" type="textarea" required>
  **Message body**
  The actual content of the email. You have full control over the layout. Use merge tags to inject form answers.
</ParamField>

<ParamField path="content_type" type="select" default="text/plain">
  **Content type**
  Determines how Mailgun parses your `body`.

  **Options:**

  * `text/plain`: Standard, unformatted text. Safe and reliable.
  * `text/html`: Allows you to write raw HTML in the `body` (e.g., `<h1>New Lead</h1>`).
</ParamField>

#### Telemetry & Attachments

<ParamField path="track_clicks" type="select" default="yes">
  **Track clicks**
  Instructs Mailgun to rewrite links inside the email to track if the recipient clicks them.
</ParamField>

<ParamField path="track_opens" type="select" default="yes">
  **Track opens**
  Instructs Mailgun to inject an invisible tracking pixel to monitor open rates.
</ParamField>

<ParamField path="attachment_fields" type="text">
  **Attachment fields**
  If your form contains File Upload blocks, type their exact names here (comma-separated). Flex Forms will automatically extract the files from the submission and attach them directly to the Mailgun email payload.
</ParamField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.