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

# SMTP Configuration

> Configure custom SMTP settings for email delivery in Runlayer

## Overview

Runlayer uses SMTP to send transactional emails such as user invitations, password resets, and system notifications. You can configure custom SMTP settings to use your preferred email provider or service.

<Note>
  All emails sent by Runlayer use the sender address `no-reply@transactional.runlayer.com`. This ensures consistency and helps with email deliverability.
</Note>

## Runlayer Managed Email Delivery

If your deployment has Runlayer managed email delivery available (powered by [Resend](https://resend.com)), you can enable it with a single toggle — no SMTP configuration required.

When enabled, Runlayer handles email delivery automatically using its built-in Resend integration. To use this:

1. Navigate to **Settings** → **Email Delivery**
2. If the "Let Runlayer handle email delivery" card is visible, toggle it **on**
3. The custom SMTP configuration form will be hidden while this is enabled

<Note>
  The "Let Runlayer handle email delivery" toggle only appears if Resend credentials are configured in your deployment's Vault. If you don't see this option, you'll need to configure a custom SMTP provider instead.
</Note>

To switch to your own SMTP provider, simply toggle Runlayer email delivery **off**. The SMTP configuration form will reappear.

## Custom SMTP Configuration

If Runlayer managed email delivery is not available, or if you prefer to use your own email provider, you can configure custom SMTP settings.

The default SMTP values are pre-filled with [Resend](https://resend.com) settings:

* **Host**: `smtp.resend.com`
* **Port**: `587`
* **Username**: `resend`
* **Encryption**: `TLS`

To use the default Resend configuration, you only need to provide an API key as the password. Contact support if you'd like us to set up a Resend account for your organization.

## Supported SMTP Providers

Runlayer works with any SMTP-compatible email service. Here are configuration examples for popular providers:

<Accordion title="Gmail / Google Workspace">
  **Settings**:

  * **Host**: `smtp.gmail.com`
  * **Port**: `587`
  * **Username**: Your Gmail address (e.g., `your-email@gmail.com`)
  * **Password**: App-specific password (not your regular Gmail password)
  * **Encryption**: `TLS`

  **Setup Steps**:

  1. Enable 2-factor authentication on your Google account
  2. Generate an [App Password](https://support.google.com/accounts/answer/185833)
  3. Use the app password in the SMTP configuration

  <Warning>
    Never use your regular Gmail password. Always use app-specific passwords for better security.
  </Warning>
</Accordion>

<Accordion title="Microsoft 365 / Outlook">
  **Settings**:

  * **Host**: `smtp-mail.outlook.com`
  * **Port**: `587`
  * **Username**: Your Microsoft 365 email address
  * **Password**: Your account password or app password
  * **Encryption**: `TLS`

  **Setup Steps**:

  1. Ensure SMTP AUTH is enabled for your organization
  2. For enhanced security, use [app passwords](https://support.microsoft.com/en-us/account-billing/using-app-passwords-with-apps-that-don-t-support-two-step-verification-5896ed9b-4263-e681-128a-a6f2979a7944)
</Accordion>

<Accordion title="Amazon SES">
  **Settings**:

  * **Host**: Regional endpoint (e.g., `email-smtp.us-east-1.amazonaws.com`)
  * **Port**: `587`
  * **Username**: Your SES SMTP username
  * **Password**: Your SES SMTP password
  * **Encryption**: `TLS`

  **Setup Steps**:

  1. Set up [Amazon SES](https://aws.amazon.com/ses/) in your AWS account
  2. Create SMTP credentials in the SES console
  3. Verify your sending domain
  4. Request production access if needed
</Accordion>

<Accordion title="SendGrid">
  **Settings**:

  * **Host**: `smtp.sendgrid.net`
  * **Port**: `587`
  * **Username**: `apikey`
  * **Password**: Your SendGrid API key
  * **Encryption**: `TLS`

  **Setup Steps**:

  1. Create a [SendGrid](https://sendgrid.com) account
  2. Generate an API key with "Mail Send" permissions
  3. Use `apikey` as the username and your API key as the password
</Accordion>

<Accordion title="Mailgun">
  **Settings**:

  * **Host**: `smtp.mailgun.org`
  * **Port**: `587`
  * **Username**: Your Mailgun SMTP username (usually starts with `postmaster@`)
  * **Password**: Your Mailgun SMTP password
  * **Encryption**: `TLS`

  **Setup Steps**:

  1. Create a [Mailgun](https://www.mailgun.com) account
  2. Add and verify your domain
  3. Find your SMTP credentials in the domain settings
</Accordion>

<Accordion title="Postmark">
  **Settings**:

  * **Host**: `smtp.postmarkapp.com`
  * **Port**: `587`
  * **Username**: Your Postmark server token
  * **Password**: Your Postmark server token
  * **Encryption**: `TLS`

  **Setup Steps**:

  1. Create a [Postmark](https://postmarkapp.com) account
  2. Create a server for transactional emails
  3. Use your server token as both username and password
</Accordion>

## Configuration Steps

<Steps>
  <Step title="Access SMTP Settings">
    1. Log in to your Runlayer dashboard
    2. Navigate to **Settings** → **Email Delivery**
    3. If Runlayer managed email delivery is enabled, toggle it off to reveal the SMTP configuration form
  </Step>

  <Step title="Enter SMTP Details">
    Fill in the required fields:

    * **SMTP Host**: Your email provider's SMTP server
    * **SMTP Port**: Usually 587 for TLS or 465 for SSL
    * **SMTP Username**: Your username or email address
    * **SMTP Password**: Your password or API key (leave empty to keep the current saved password)
    * **Encryption**: Choose TLS (recommended) or SSL
  </Step>

  <Step title="Save and Test">
    1. Click **Save Configuration** to store your SMTP settings
    2. Click **Send Test Email** to verify everything works — a test email will be sent to your account email address
    3. Check that you receive the test email successfully

    <Note>
      You can use **Reset to Default** to revert the form fields to the currently saved values.
    </Note>
  </Step>
</Steps>

## Email Notifications

The Email Delivery settings page also includes notification preferences that control which system events trigger email notifications to organization admins:

* **New Server Requests**: Notify admins when employees request new MCP servers (enabled by default)

<Note>
  Notifications require SMTP to be configured (or Runlayer managed email delivery to be enabled). Notification emails are sent to all organization admins via BCC.
</Note>

## Troubleshooting

<Accordion title="Authentication Failed">
  **Common causes**:

  * Incorrect username or password
  * 2FA enabled without app password
  * SMTP not enabled for the account

  **Solutions**:

  * Verify your credentials
  * Generate an app-specific password
  * Check your email provider's SMTP settings
</Accordion>

<Accordion title="Connection Timeout">
  **Common causes**:

  * Incorrect host or port
  * Firewall blocking SMTP traffic
  * Wrong encryption settings

  **Solutions**:

  * Verify the SMTP host and port
  * Check firewall settings
  * Try different encryption options (TLS vs SSL)
</Accordion>

<Accordion title="Emails Not Delivered">
  **Common causes**:

  * Sender domain not verified
  * Email marked as spam
  * Rate limits exceeded

  **Solutions**:

  * Verify your sending domain with your email provider
  * Check spam folders
  * Review your email provider's sending limits
</Accordion>

<Accordion title="SSL/TLS Certificate Errors">
  **Common causes**:

  * Outdated certificates
  * Self-signed certificates
  * Certificate name mismatch

  **Solutions**:

  * Ensure your system's certificate store is up to date
  * Contact your email provider for certificate issues
  * Try using a different encryption method
</Accordion>

## Rate Limits and Quotas

Different email providers have various sending limits:

| Provider   | Free Tier Daily Limit | Notes                     |
| ---------- | --------------------- | ------------------------- |
| Gmail      | 500 emails            | Per day, per account      |
| Outlook    | 300 emails            | Per day, per account      |
| SendGrid   | 100 emails            | Per day for free accounts |
| Mailgun    | 100 emails            | First month free          |
| Amazon SES | 200 emails            | Per day in sandbox mode   |
| Resend     | 100 emails            | Per day for free accounts |

<Note>
  For production use with high email volumes, consider upgrading to paid plans or enterprise solutions.
</Note>

## Getting Help

If you encounter issues with SMTP configuration:

<CardGroup cols={2}>
  <Card title="Test Configuration" icon="flask">
    Use the "Send Test Email" button to verify your settings
  </Card>

  <Card title="Check Provider Documentation" icon="book">
    Consult your email provider's SMTP documentation
  </Card>

  <Card title="Contact Support" icon="envelope">
    Reach out to our support team for assistance
  </Card>

  <Card title="Enterprise Setup" icon="building">
    Contact us for enterprise SMTP configuration assistance
  </Card>
</CardGroup>