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

# Set Up a ChatbotX Email Channel Using SMTP Credentials

> Connect any email address to ChatbotX via SMTP, collect opt-ins, build automated email flows, track performance with Email Topics, and fix common errors.

The Email channel lets you turn any email address into a ChatbotX inbox. Incoming emails appear as conversations, and your team can reply directly from ChatbotX. Using an SMTP connection, you can also send automated emails — notifications, order confirmations, documents, or entire email sequences — directly from your Flows.

<Warning>
  **Email deliverability:** To ensure your emails are not marked as spam and achieve the highest delivery rate, configure domain authentication (**SPF**, **DKIM**, and **DMARC**) in your sending domain's DNS manager before using it in a production environment.
</Warning>

***

## Step 1: Get SMTP Credentials from Your Provider

Depending on the email service provider you use, you will need the following basic information to connect with ChatbotX:

* **SMTP Host/Server**
* **SMTP Port** — usually `465` for SSL or `587` for TLS
* **SMTP Username** — usually your email address
* **SMTP Password** — an App Password or API Key, **not your main account login password**

Expand your email provider below to see how to obtain the correct credentials.

<AccordionGroup>
  <Accordion title="1. Gmail / Google Workspace">
    <Steps>
      <Step title="Enable 2-Step Verification">
        Log in to your Google account, go to the **Security** section, and make sure you have turned on **2-Step Verification**.
      </Step>

      <Step title="Create an App Password">
        Still in the **Security** section, find the **App passwords** section.
      </Step>

      <Step title="Get the password">
        Enter an app name (for example, `ChatbotX SMTP`) and click **Create**. Google will provide you with a 16-letter string. This is your **SMTP Password**.
      </Step>

      <Step title="Connection parameters">
        * **Host:** `smtp.gmail.com`
        * **Port:** `465` (SSL) or `587` (TLS)
        * **Username:** your Gmail address

        See the official documentation for more details: [Sign in with App Passwords — Google Account Help](https://support.google.com/accounts/answer/185833)
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="2. Outlook / Office 365">
    <Steps>
      <Step title="Access security settings">
        Log in to your Microsoft account, go to **Security → Advanced Security Options**.
      </Step>

      <Step title="Create an App Password">
        Ensure **Two-step verification** is turned on. Then scroll down to the **App passwords** section and click **Create a new app password**.
      </Step>

      <Step title="Get the password">
        Save the newly created password. This is your **SMTP Password**.
      </Step>

      <Step title="Connection parameters">
        * **Host:** `smtp-mail.outlook.com` (or `smtp.office365.com` for business accounts)
        * **Port:** `587` (TLS)
        * **Username:** your Outlook/Office 365 email address

        See the official documentation for more details: [Manage app passwords — Microsoft Support](https://support.microsoft.com/account-billing/how-to-get-and-use-app-passwords-5896ed9b-4263-e681-128a-a6f2979a7944)
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="3. SendGrid (Twilio)">
    <Steps>
      <Step title="Create an API Key">
        Log in to SendGrid, go to **Settings → API Keys**, and click **Create API Key**.
      </Step>

      <Step title="Assign permissions">
        Select **Restricted Access**, grant **Mail Send → Full Access**, and proceed to create.
      </Step>

      <Step title="Get the information">
        Copy the API Key string starting with `SG.`. This will be your **SMTP Password**.
      </Step>

      <Step title="Connection parameters">
        * **Host:** `smtp.sendgrid.net`
        * **Port:** `465` (SSL) or `587` (TLS)
        * **Username:** `apikey` (write exactly `apikey`, not your email)

        See the official documentation for more details: [Sending Email with SMTP — Twilio SendGrid Docs](https://docs.sendgrid.com/for-developers/sending-email/getting-started-smtp)
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="4. Amazon SES">
    <Steps>
      <Step title="Access SMTP Settings">
        In the AWS console, open the **Amazon SES** service, and navigate to **SMTP Settings**.
      </Step>

      <Step title="Create SMTP credentials">
        Click **Create My SMTP Credentials**. The system will create a new IAM user with permissions to send emails.
      </Step>

      <Step title="Get Username and Password">
        Download or immediately copy the provided **SMTP Username** and **SMTP Password** on the final screen.
      </Step>

      <Step title="Connection parameters">
        * **Host:** depends on your region, for example `email-smtp.us-east-1.amazonaws.com`
        * **Port:** `465` or `587`
        * **Username:** the newly created SMTP Username string
        * **Password:** the newly created SMTP Password string

        See the official documentation for more details: [Obtaining SMTP credentials — Amazon SES Developer Guide](https://docs.aws.amazon.com/ses/latest/dg/send-email-smtp.html)
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="5. Brevo (Sendinblue)">
    <Steps>
      <Step title="Access SMTP & API">
        Log in to Brevo, click on your account name in the top right corner, then select **SMTP & API**.
      </Step>

      <Step title="Generate a new SMTP key">
        Switch to the **SMTP** tab, and click **Generate a new SMTP key**.
      </Step>

      <Step title="Get the password">
        Name the key and copy the newly generated key string.
      </Step>

      <Step title="Connection parameters">
        * **Host:** `smtp-relay.brevo.com`
        * **Port:** `587`
        * **Username:** your Brevo login email
        * **Password:** the newly created SMTP key string

        See the official documentation for more details: [Set up Brevo SMTP — Brevo Help Center](https://help.brevo.com/hc/en-us/articles/209432609-Set-up-Brevo-SMTP)
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Step 2: Create an Email Channel

<Steps>
  <Step title="Add a new Email channel">
    In ChatbotX, go to **Settings → Channels** and click **Add SMTP**.
  </Step>

  <Step title="Choose a Provider">
    Find and select your email service provider from the dropdown list (for example, Google (Gmail), Outlook, SendGrid, Amazon SES).
  </Step>

  <Step title="Enter SMTP connection details">
    Fill in the SMTP credentials obtained in Step 1:

    | Field            | Description                                                                                                               |
    | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
    | **Host**         | The provider's SMTP server (for example, `smtp.gmail.com`)                                                                |
    | **Port**         | The SMTP connection port (usually `587` or `465`)                                                                         |
    | **Username**     | SMTP login name (usually the email address)                                                                               |
    | **Password**     | App Password or SMTP Key (not the main login password)                                                                    |
    | **From Address** | The email address that will appear as the sender when customers receive the email (for example, `noreply@yourdomain.com`) |
  </Step>

  <Step title="Connect">
    Click **Connect** to finish the SMTP configuration setup.
  </Step>
</Steps>

***

## Step 3: Request Permission (Opt-In) and Collect Customer Email

Before you can send emails to customers via a ChatbotX Flow, you **must** have two elements: the customer's email address stored in their profile, and the customer's explicit consent to receive emails (Email Opt-In).

<Steps>
  <Step title="Collect email using Get User Data">
    Use the **Get User Data** block in the Flow to ask for the customer's email address. In the **Reply Format** section, select the **Email** format and save the result to an **Output Custom Field** (for example, an `email` field).
  </Step>

  <Step title="Mark Email Opt-in">
    After the customer provides their email, create an Action block:

    1. Click the **+** sign and select **Perform Action**.
    2. Click the newly created Action block and select **Email Actions**.
    3. Select **Opt In Email**.

    <Warning>
      The **Opt In Email** status is mandatory. The system will not allow you to send emails to a contact who has not been explicitly opted in.
    </Warning>
  </Step>
</Steps>

***

## Step 4: Set Up Automated Email Sending in Flow

Once customers have agreed to receive emails, you can automatically send emails anywhere in your Flow.

<Steps>
  <Step title="Add the Send Mail node">
    In the Flow workspace, click the **+** button to open the node menu. Select **Send Mail** from the list.
  </Step>

  <Step title="Choose the sending channel and topic">
    In the **Send Mail** configuration panel, choose the **SMTP Channel** that should send this email. If you have connected more than one SMTP channel, select the sender that matches this Flow.

    You can also choose a **Topic ID**. An Email Topic helps you track email performance and run actions based on how contacts interact with your emails.
  </Step>

  <Step title="Fill in the email details">
    Complete the main fields in the **Send Mail** panel:

    * **From** — the sender email address. You can use a fixed address or a variable such as `{{email}}` if your Flow needs a dynamic sender.
    * **To** — by default, the system sends to the current user's email (if provided). You can also set it to send internal notification emails to your team.
    * **Subject** — the subject of the email. You can use variables (for example, `{{first_name}}`) to personalize the subject.
    * **Preheader** — the short preview text that appears in many inboxes under the subject line.
  </Step>

  <Step title="Compose the email content">
    Build the email body with the editor inside the **Send Mail** panel. You can add **Heading**, **Text**, **Image**, **Button**, **Line**, **Spacing**, and **Code** blocks. Use variables from the contact profile or Custom Fields to personalize the message, such as order details, customer name, or support ticket information.
  </Step>

  <Step title="Test and Publish">
    Click your Flow's **Publish** button. Interact with the bot to verify that the system has successfully sent the email to your inbox.
  </Step>
</Steps>

***

## Manage Email Topics in Flows

**Email Topics** help you group emails sent from Flows and track how contacts interact with them. Use topics when you want to compare email performance across campaigns, order updates, onboarding messages, or internal notifications. You can manage Email Topics from the **Flows** menu.

<Steps>
  <Step title="Open Flows">
    In the left sidebar, click **Flows**.
  </Step>

  <Step title="Open Email Topics">
    In the Flows page, select the **Email Topics** tab.
  </Step>

  <Step title="Add a topic">
    Click **Add** to create a new Email Topic.
  </Step>

  <Step title="Name the topic">
    Enter a clear topic name, such as `Order confirmation`, `Welcome email`, or `Monthly promotion`.
  </Step>

  <Step title="Create the topic">
    Click the create button to save the topic. The topic is then available in the **Topic ID** field inside the **Send Mail** node.
  </Step>
</Steps>

### Email Topic Statistics

The Email Topics page includes a statistics table for each topic.

| Column        | Description                                                          |
| ------------- | -------------------------------------------------------------------- |
| **Name**      | The Email Topic name                                                 |
| **Sent**      | The number of emails sent with this topic                            |
| **Delivered** | The percentage of emails delivered successfully                      |
| **Seen**      | The percentage of emails opened or seen by contacts                  |
| **Clicked**   | The percentage of contacts who clicked a link or button in the email |

<Tip>
  When you configure a **Send Mail** node, you can select an existing topic in **Topic ID**. If the topic does not exist yet, click **Add New** next to the field to create it quickly without leaving the Flow editor.
</Tip>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: 'Authentication Failed' or 'Invalid Login'">
    **Cause:** Incorrect SMTP Username or Password.

    **Solution:** Do not use your main login password. Ensure you have created and used a separate **App Password** or **API Key/SMTP Key** as instructed in Step 1.
  </Accordion>

  <Accordion title="Timeout or Connection Refused Error">
    **Cause:** Incorrect SMTP Port or blocked by a firewall.

    **Solution:** Make sure the Port matches the correct encryption standard — Port `465` must use SSL, Port `587` must use TLS. If using Google Workspace, ensure IMAP/SMTP access is not disabled by the administrator.
  </Accordion>

  <Accordion title="Flow passes the Send Mail node but the email does not arrive">
    **Cause:** The customer has not been granted permission (Email Opt-in) in the system.

    **Solution:** Check the Audience data to see if the user has an email address and the **Opted-in** status. Ensure your Flow has a step passing through the `Set Email Opt-In` Action before reaching `Send Mail`.
  </Accordion>

  <Accordion title="Sent emails land in Spam folder">
    **Solution:** Configure DNS records (`SPF`, `DKIM`) for the domain displayed in the sending email (From Address). Avoid sending emails that contain too many images without text, or that use "spammy" words in the subject line.
  </Accordion>
</AccordionGroup>