# Email Providers

AdaTrack sends transactional emails for user registration (OTP codes), password resets, email change confirmations, scheduled report delivery, and workflow notifications. The platform supports multiple email backends so you can choose the one that fits your infrastructure.

***

## Supported Providers

| Provider            | Best For                                                                  | Configuration              |
| ------------------- | ------------------------------------------------------------------------- | -------------------------- |
| **SMTP**            | Self-hosted deployments, corporate mail servers, AWS SES, Gmail, SendGrid | Standard SMTP credentials  |
| **Mailgun**         | SaaS deployments already using the Mailgun API                            | Mailgun API key and domain |
| **No-op (Console)** | Local development and testing                                             | No configuration needed    |

***

## Choosing a Provider

Set the `EMAIL_PROVIDER` environment variable to explicitly select your email backend:

```bash
EMAIL_PROVIDER=smtp      # Use a generic SMTP server
EMAIL_PROVIDER=mailgun   # Use the Mailgun API
EMAIL_PROVIDER=noop      # Log emails to the console (no delivery)
```

If `EMAIL_PROVIDER` is not set, AdaTrack auto-detects the provider:

1. If `MAILGUN_API_KEY` is present, Mailgun is used.
2. If `SMTP_HOST` is present, SMTP is used.
3. Otherwise, the system falls back to console logging (no-op).

> **Existing deployments:** If you already have `MAILGUN_*` environment variables configured, everything continues to work with no changes required.

***

## SMTP Configuration

SMTP is the recommended provider for self-hosted deployments. It works with any SMTP-compatible server including Gmail, AWS SES, SendGrid, Office 365, Postfix, and local mail relays like MailHog.

### Required Variables

| Variable         | Description                                                                   |
| ---------------- | ----------------------------------------------------------------------------- |
| `EMAIL_PROVIDER` | Set to `smtp` (or leave empty if `SMTP_HOST` is set).                         |
| `EMAIL_SENDER`   | The "From" address for all outbound emails (e.g., `noreply@yourcompany.com`). |
| `SMTP_HOST`      | SMTP server hostname (e.g., `smtp.gmail.com`).                                |

### Optional Variables

| Variable          | Default | Description                                                                   |
| ----------------- | ------- | ----------------------------------------------------------------------------- |
| `SMTP_PORT`       | `587`   | SMTP server port. Use `587` for STARTTLS or `465` for implicit TLS.           |
| `SMTP_USERNAME`   | —       | Authentication username.                                                      |
| `SMTP_PASSWORD`   | —       | Authentication password. Store as a secret in production.                     |
| `SMTP_AUTH`       | `plain` | Authentication method: `plain`, `login`, `crammd5`, or `none`.                |
| `SMTP_TLS`        | `false` | Set to `true` to force an implicit TLS connection (required for port 465).    |
| `EMAIL_RECIPIENT` | —       | Destination address for contact form submissions. Defaults to `EMAIL_SENDER`. |

### Example Configurations

**Gmail / Google Workspace:**

```env
EMAIL_PROVIDER=smtp
EMAIL_SENDER=noreply@yourcompany.com
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=noreply@yourcompany.com
SMTP_PASSWORD=your-app-specific-password
SMTP_AUTH=plain
```

> You must generate an [App Password](https://support.google.com/accounts/answer/185833) in your Google Account settings. Regular passwords will not work with 2FA enabled.

**AWS SES (SMTP Interface):**

```env
EMAIL_PROVIDER=smtp
EMAIL_SENDER=noreply@yourcompany.com
SMTP_HOST=email-smtp.eu-west-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=AKIA...
SMTP_PASSWORD=your-ses-smtp-password
SMTP_AUTH=plain
```

**Office 365 / Exchange:**

```env
EMAIL_PROVIDER=smtp
EMAIL_SENDER=noreply@yourcompany.com
SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_USERNAME=noreply@yourcompany.com
SMTP_PASSWORD=your-password
SMTP_AUTH=login
```

> Office 365 and Exchange servers require the `login` authentication method instead of `plain`.

**Local Relay (Postfix / MailHog — no authentication):**

```env
EMAIL_PROVIDER=smtp
EMAIL_SENDER=noreply@yourcompany.com
SMTP_HOST=localhost
SMTP_PORT=25
SMTP_AUTH=none
```

> Only use `SMTP_AUTH=none` on trusted internal networks. Never use it over the public internet.

***

## Mailgun Configuration

Mailgun is the default provider for the AdaTrack SaaS platform. It uses the Mailgun HTTP API (EU region) for delivery.

| Variable            | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| `MAILGUN_API_KEY`   | Your Mailgun private API key.                                           |
| `MAILGUN_DOMAIN`    | Your Mailgun sending domain (e.g., `mg.yourcompany.com`).               |
| `MAILGUN_SENDER`    | The "From" address for all emails.                                      |
| `MAILGUN_RECIPIENT` | Destination for contact form submissions. Defaults to `MAILGUN_SENDER`. |

```env
MAILGUN_API_KEY=key-abc123def456
MAILGUN_DOMAIN=mg.yourcompany.com
MAILGUN_SENDER=noreply@yourcompany.com
```

> When migrating from Mailgun to SMTP, you can keep both sets of variables and set `EMAIL_PROVIDER=smtp` to switch explicitly.

***

## No-op (Console Logging)

When no email provider is configured, or when `EMAIL_PROVIDER=noop` is set, all emails are logged to the server console instead of being delivered. This is useful for local development — OTP codes and password reset links will appear in the server logs.

```
WARNING: Email not configured. OTP for user@example.com: 482910 (valid for 10 minutes)
```

***

## Shared Variables

These variables apply across all providers:

| Variable       | Default                 | Description                                                                                                           |
| -------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `FRONTEND_URL` | `http://localhost:5173` | Base URL used to construct links in emails (password reset, email confirmation). Must match your actual frontend URL. |

***

## Troubleshooting

**Emails are not being delivered:**

* Check the server logs for error messages from the email provider.
* Verify that your SMTP credentials are correct and that your server allows connections from the AdaTrack host.
* For Gmail, ensure you are using an App Password, not your account password.
* For AWS SES, verify that your sending domain and sender address are verified in the SES console.

**OTP codes appear in logs instead of being emailed:**

* This means no email provider is configured. Set `EMAIL_PROVIDER` and the required variables for your chosen provider.

**TLS handshake errors:**

* If connecting to port 465, set `SMTP_TLS=true`.
* If connecting to port 587, ensure the server supports STARTTLS (most modern servers do).

**Authentication failures with Office 365:**

* Use `SMTP_AUTH=login` instead of the default `plain`.