> ## 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.

# SendGrid Integration

> A comprehensive guide to overriding standard SMTP and routing all transactional emails and autoresponders via SendGrid's robust V3 API.

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

The **SendGrid** integration provides an absolute enterprise-grade transport layer for Flex Forms. By bypassing standard, often rate-limited SMTP connections, Flex Forms connects directly to SendGrid's V3 API. This guarantees lightning-fast, high-deliverability routing for critical form receipts and administrative notifications.

## Enterprise Business Use Cases

<CardGroup cols={2}>
  <Card title="Guaranteed Inbox Placement" icon="shield-check">
    Standard PHP SMTP on shared servers is frequently blacklisted by major providers (Gmail, Outlook). The SendGrid API integration ensures your critical "Thank You for Contacting Us" receipts are digitally signed and actually land in the primary inbox.
  </Card>

  <Card title="Massive Concurrency Routing" icon="route">
    If your Flex Form goes viral and receives 500 submissions in a single minute, a standard SMTP queue will immediately crash. The SendGrid API handles massive concurrency, effortlessly routing hundreds of administrative notification emails simultaneously without dropping a single one.
  </Card>
</CardGroup>

***

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

Connecting Flex Forms to SendGrid requires generating a highly secure, restricted API Key. Follow these exact instructions to ensure the integration is properly authenticated.

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

  <Step title="Step 2: Access the Settings Menu">
    Once logged in, look at the **left-hand sidebar navigation menu**. Scroll down to the bottom of the list and locate the section labeled **Settings**. Click to expand it.
  </Step>

  <Step title="Step 3: Navigate to API Keys">
    In the expanded "Settings" sub-menu, click exactly on the link labeled **API Keys**. This will take you to the secure credentials center.
  </Step>

  <Step title="Step 4: Initiate Key Generation">
    In the top right corner of the API Keys page, click the prominent blue button labeled **Create API Key**. A configuration screen will slide out or appear in a modal.
  </Step>

  <Step title="Step 5: Name the Key">
    In the "API Key Name" field, type exactly: `Flex Forms Production API`. Giving it a descriptive name ensures your security team will not accidentally delete it during future audits.
  </Step>

  <Step title="Step 6: Assign Strict Permissions (Crucial Step)">
    Under "API Key Permissions", DO NOT select "Full Access" (this is a massive security risk).

    Instead, select **Restricted Access**. A massive list of permissions will appear. Scroll down the list until you find the section explicitly labeled **Mail Send**. Click on it to expand it, and move the slider to grant **Full Access** ONLY to the "Mail Send" capability. You do not need to grant any other permissions.
  </Step>

  <Step title="Step 7: Copy the API Key">
    Click the **Create & View** button at the bottom of the screen.

    SendGrid will generate a very long string of alphanumeric characters starting with `SG.`.

    <Callout type="critical">
      **CRITICAL WARNING:** You must copy this token immediately. For security reasons, SendGrid will *never* display this full token to you again. If you lose it, you must revoke it and start over at Step 4.
    </Callout>

    Click the token string to copy it to your clipboard.
  </Step>

  <Step title="Step 8: Create a Connection (recommended)">
    Switch to Flex Forms → **Integrations** → **Connections**. Create a **SendGrid** connection, paste the `SG.` API key, and connect. For a single shared account you can use Catalog → SendGrid instead.
  </Step>
</Steps>

On each form that should send via SendGrid, open hub **Integrations** → **SendGrid**, enable the feed, and pick the **Connection**.

***

## Configuration & Masterclass Usage

Once SendGrid 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 SendGrid, as it simply acts as the delivery engine for emails formatted by Flex Forms.

### The Domain Authentication Trap

<Tree>
  <Tree.Folder name="Strict Sender Validation" defaultOpen>
    <Tree.File name="If you verified the domain: yourcompany.com in SendGrid's Sender Authentication settings." />

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

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

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

    <Tree.File name="SendGrid instantly DROPS the email and throws a 403 Forbidden 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 SendGrid (SendGrid Settings > Sender Authentication). If you try to send from an unverified domain, the email will simply disappear into the void.
</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, missing the `SG.` prefix, or contains a trailing space. If you verify the key is correct, it means a SendGrid administrator deleted or revoked the key. Generate a new one and update Flex Forms.
  </Accordion>

  <Accordion title="API Error: 403 Forbidden">
    **The Problem:** The server logs show a `403 Forbidden` error when attempting to send.

    **The Solution:** You have encountered the Domain Authentication Trap. The "From Address" defined in Flex Forms is not authorized in SendGrid. Either change the From Address in Flex Forms, or log into SendGrid and complete the "Sender Authentication" process for that domain.
  </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>
  **SendGrid API Key**
  The master API key that allows Flex Forms to send emails via SendGrid's v3 Mail Send API. Create this in **Settings → API Keys**. It *must* have the `mail.send` permission scope.
</ParamField>

<ParamField path="default_from_email" type="text">
  **Default from email**
  The fallback sender address (e.g., `noreply@example.com`). **CRITICAL:** The domain in this email address *must* be fully authenticated in your SendGrid Sender Authentication settings. SendGrid will silently drop 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 dynamically send the email to the respondent (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 SendGrid 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 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 SendGrid 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>`). SendGrid will automatically generate a plain-text fallback version for older clients.
</ParamField>

#### Attachments

<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, Base64 encode them, and inject them directly into the SendGrid JSON payload as native email attachments.
</ParamField>


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