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

# SMTP

> Configure SMTP so OpenSRE can send email through your existing relay.

## Overview

OpenSRE can send email through any existing SMTP relay you already use. You do **not** need to run your own mail server.

Typical providers:

* Google Workspace / Gmail SMTP
* Microsoft 365 SMTP
* AWS SES SMTP
* SendGrid / Postmark / Mailgun SMTP
* local dev SMTP sinks like Mailpit or MailHog

## Prerequisites

* An SMTP host you can reach from OpenSRE
* A sender address the relay will accept
* Optional username/password if the relay requires auth

## Setup

### Option 1: CLI wizard

```bash theme={null}
opensre integrations setup smtp
```

You'll be prompted for:

* SMTP host
* SMTP port
* security mode: `starttls`, `ssl`, or `none`
* optional username/password
* sender address
* optional default recipient

SMTP is configured separately from first-run onboarding — use this setup command.

### Option 2: Environment variables

```bash theme={null}
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURITY=starttls
SMTP_USERNAME=mailer
SMTP_PASSWORD=secret
SMTP_FROM_ADDRESS=opensre@example.com
SMTP_DEFAULT_TO=team@example.com
```

| Variable | Default | Description |
| - | - | - |
| `SMTP_HOST` | — | SMTP hostname |
| `SMTP_PORT` | `587` | SMTP port |
| `SMTP_SECURITY` | `starttls` | `starttls`, `ssl`, or `none` |
| `SMTP_USERNAME` | — | Optional auth username (set with password) |
| `SMTP_PASSWORD` | — | Optional auth password (set with username) |
| `SMTP_FROM_ADDRESS` | — | Sender address |
| `SMTP_DEFAULT_TO` | — | Default recipient for outbound email |

If authentication is required, set **both** `SMTP_USERNAME` and `SMTP_PASSWORD`.

## Credentials

Use any SMTP relay your org already trusts. For local testing, Mailpit is a good fake SMTP target:

```bash theme={null}
docker run -p 1025:1025 -p 8025:8025 axllent/mailpit
```

```bash theme={null}
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_SECURITY=none
SMTP_FROM_ADDRESS=opensre@example.com
SMTP_DEFAULT_TO=team@example.com
```

## Verify

```bash theme={null}
opensre integrations verify smtp
```

A passing verification confirms OpenSRE can:

* connect to the SMTP server
* negotiate TLS when configured
* authenticate when credentials are provided

Sample success output:

```text theme={null}
smtp: passed — Connected to SMTP server successfully.
```

## Troubleshooting

| Detail | Likely cause |
| - | - |
| `Missing recipient email address` | No `SMTP_DEFAULT_TO` is configured yet. |
| `username and password must both be set` | Only one auth field was provided. |
| `from_address must look like an email address` | Sender address is malformed. |
| `SMTP connection failed` | Host/port/TLS settings are wrong, or the relay is unreachable. |

## Security

* Prefer app passwords / SMTP credentials scoped to a mailer account.
* Store passwords in `.env` or your secret manager — not in source control.
* Use `starttls` or `ssl` in production; reserve `none` for local sinks.


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