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

# Setting up SMTP providers

> Troubleshoot SMTP configuration in the HoopAI platform including Mailgun, SendGrid, and custom SMTP setup, authentication failures, SPF/DKIM/DMARC records, and email deliverability.

The HoopAI platform supports custom SMTP providers so you can send emails from your own domain. This guide covers how to configure popular SMTP services, troubleshoot authentication failures, set up DNS records for deliverability, and resolve common email issues.

***

## Connecting an SMTP provider

<Steps>
  <Step title="Open email settings">
    Navigate to **Settings > Email Services > SMTP** in your Hoop account.
  </Step>

  <Step title="Enter your SMTP credentials">
    Fill in the following fields:

    * **SMTP Host** — Your provider's SMTP server address
    * **Port** — Typically 587 (TLS) or 465 (SSL)
    * **Username** — Your SMTP username or API key
    * **Password** — Your SMTP password or API secret
    * **From Email** — The email address recipients will see
    * **From Name** — The display name for outgoing emails
  </Step>

  <Step title="Save and send a test email">
    Click **Save** and then **Send Test Email** to verify the connection. Check your inbox for the test message.
  </Step>
</Steps>

***

## Provider-specific settings

| Provider         | SMTP host                         | Port       | Username                    | Notes                                                       |
| ---------------- | --------------------------------- | ---------- | --------------------------- | ----------------------------------------------------------- |
| Mailgun          | smtp.mailgun.org                  | 587        | Your Mailgun SMTP username  | Use the domain-specific credentials, not your account login |
| SendGrid         | smtp.sendgrid.net                 | 587        | `apikey` (literal string)   | The password is your SendGrid API key                       |
| Google Workspace | smtp-relay.gmail.com              | 587        | Your Google Workspace email | Requires an app password if 2FA is enabled                  |
| Amazon SES       | email-smtp.{region}.amazonaws.com | 587        | Your SES SMTP username      | Generate SMTP credentials from the AWS SES console          |
| Custom SMTP      | Varies                            | 587 or 465 | Varies                      | Confirm TLS/SSL support with your provider                  |

<Note>
  Some providers require you to verify your sending domain before SMTP access is enabled. Complete domain verification on the provider's dashboard before configuring Hoop.
</Note>

***

## DNS records for email deliverability

To prevent your emails from landing in spam, configure these DNS records for your sending domain:

### SPF record

Add a TXT record to your domain's DNS that authorizes your SMTP provider to send on your behalf:

```txt theme={null}
v=spf1 include:mailgun.org ~all
```

Replace `mailgun.org` with your provider's SPF include value.

### DKIM record

Your SMTP provider generates a DKIM key pair. Add the public key as a TXT or CNAME record in your DNS. This allows receiving servers to verify that your emails have not been tampered with.

### DMARC record

Add a DMARC TXT record at `_dmarc.yourdomain.com`:

```txt theme={null}
v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@yourdomain.com
```

<Tip>
  Start with `p=none` while monitoring DMARC reports, then move to `p=quarantine` or `p=reject` once you confirm legitimate emails are passing authentication.
</Tip>

***

## Common SMTP issues

<AccordionGroup>
  <Accordion title="Authentication failed (535 error)">
    Double-check your username and password. For SendGrid, the username must be the literal string `apikey`. For Mailgun, use the domain-specific SMTP credentials found under **Sending > Domain Settings**, not your account login. If you recently rotated credentials, update them in Hoop.
  </Accordion>

  <Accordion title="Connection timed out">
    Verify the SMTP host and port are correct. Port 587 with STARTTLS is the most widely supported option. If port 587 is blocked by your network, try port 465 with SSL. Also confirm that your provider has not suspended your account for billing issues.
  </Accordion>

  <Accordion title="Emails landing in spam">
    Ensure SPF, DKIM, and DMARC records are correctly configured. Use an online mail testing tool to check your email score. Avoid sending from free email domains (gmail.com, yahoo.com) through custom SMTP — always use your business domain.
  </Accordion>

  <Accordion title="Emails bouncing back">
    Check the bounce type. A **hard bounce** means the recipient address is invalid — remove it from your list. A **soft bounce** means a temporary issue like a full mailbox. Hoop automatically retries soft bounces up to three times. Review bounced addresses under **Settings > Email Services > Bounce Log**.
  </Accordion>

  <Accordion title="From address mismatch error">
    Your SMTP provider may reject emails if the "From Email" in Hoop does not match a verified sender address or domain on the provider. Verify the sending domain or add the specific email address in your provider's dashboard.
  </Accordion>
</AccordionGroup>

***

## Testing your SMTP configuration

After setup, verify that everything works:

1. Send a test email from **Settings > Email Services > SMTP > Send Test Email**
2. Check the email headers in the received message to confirm SPF, DKIM, and DMARC all pass
3. Send a test email from a workflow to confirm Hoop uses the custom SMTP connection for automated emails
4. Monitor the **Email Log** under **Settings > Email Services** for delivery status and error messages

<Warning>
  If you change SMTP providers, update your DNS records immediately. Outdated SPF or DKIM records will cause authentication failures and increase the chance of emails being marked as spam.
</Warning>