# Email Configuration Commands

## Overview <a href="#overview" id="overview"></a>

The `email-config` command manages email provider configurations used for sending one-time share links and notifications directly from Commander. Configurations are stored encrypted in your Keeper vault. By sending secure emails through Commander, zero knowledge is preserved and Keeper's backend servers have no access to the content.

**Supported Providers:**

* **SMTP** - Available on all installations (binary, pip, pip with \[email])
* **SendGrid** - Only available with `pip install keepercommander[email]`
* **AWS SES** - Only available with `pip install keepercommander[email]`
* **Gmail OAuth** - Only available with `pip install keepercommander[email]`
* **Microsoft OAuth** - Only available with `pip install keepercommander[email]`

{% hint style="warning" %}
**Note:** Binary installations and basic pip installations `pip install keepercommander` only support SMTP.
{% endhint %}

## Use Cases

The email configuration is used when sending emails directly from Commander, using the customer's configured email provider instead of sending the email through Keeper's servers. Use cases where this is applicable include:

* Sending one-time share links with the [record-add](https://docs.keeper.io/keeperpam/commander-cli/command-reference/record-commands#record-add-and-record-update-commands) command
* Rotating a password and sending a one-time share with the [pam action rotate](https://docs.keeper.io/en/keeperpam/commander-cli/keeperpam-commands#rotate) command
* Automating the rotation and delivery of new employee credentials with the [credential-provision](https://docs.keeper.io/en/keeperpam/commander-cli/command-reference/automation-commands) command

## Email Configuration Commands

| [`create`](#email-config-create) | Create new email provider configuration |
| -------------------------------- | --------------------------------------- |
| [`list`](#email-config-list)     | List all configured email providers     |
| [`test`](#email-config-test)     | Test email configuration                |
| [`delete`](#email-config-delete) | Delete email configuration              |
| [`update`](#email-config-update) | Update existing email configuration     |

### email-config create <a href="#email-config-create" id="email-config-create"></a>

**Command:** `email-config create`

**Detail:** Create a new email provider configuration. Configurations are stored encrypted in your Keeper vault and can be used with `record-add` and `one-time-share` commands.

**Common Parameters:**

* `--name <NAME>` - Configuration name (required)
* `--provider <PROVIDER>` - Provider type: `smtp`, `sendgrid`, `ses`, `gmail-oauth`, `microsoft-oauth` (required)
* `--from-address <EMAIL>` - Sender email address (required)
* `--from-name <NAME>` - Sender display name (optional)

**SMTP Provider Parameters:**

* `--smtp-host <HOST>` - SMTP server hostname
* `--smtp-port <PORT>` - SMTP server port (default: 587)
* `--smtp-username <USERNAME>` - SMTP username
* `--smtp-password <PASSWORD>` - SMTP password
* `--smtp-use-tls` | `--smtp-no-tls` - Enable / Disable TLS
* `--smtp-use-ssl` - Enable SSL

**SendGrid Provider Parameters:**

* `--sendgrid-api-key <KEY>` - SendGrid API key

**AWS SES Provider Parameters:**

* `--aws-region <REGION>` - AWS region (e.g., us-east-1)
* `--aws-access-key <KEY>` - AWS access key ID
* `--aws-secret-key <SECRET>` - AWS secret access key

**OAuth Provider Parameters (Gmail and Microsoft):**

* `--oauth-client-id <ID>` - OAuth client ID
* `--oauth-client-secret <SECRET>` - OAuth client secret
* `--oauth-tenant-id <ID>` - Azure tenant ID (Microsoft only, use 'common' for multi-tenant)
* `--oauth-port <PORT>` - Local callback port (default: 8080)

**OAuth Manual Token Parameters (Advanced):**

* `--oauth-access-token <TOKEN>` - Access token
* `--oauth-refresh-token <TOKEN>` - Refresh token
* `--oauth-token-expiry <DATETIME>` - Token expiry (ISO-8601 format)

**Examples:**

```bash
# SMTP with Gmail
email-config create \
  --name 'SMTP-Gmail' \
  --provider smtp \
  --from-address 'you@gmail.com' \
  --from-name 'Your Name' \
  --smtp-host 'smtp.gmail.com' \
  --smtp-port 587 \
  --smtp-use-tls \
  --smtp-use-ssl \
  --smtp-username 'you@gmail.com' \
  --smtp-password 'app-password'

# SendGrid
email-config create \
  --name 'SendGrid' \
  --provider sendgrid \
  --from-address 'verified@yourdomain.com' \
  --sendgrid-api-key 'SG.xxx'

# Gmail OAuth (interactive flow)
email-config create \
  --name 'Gmail-OAuth' \
  --provider gmail-oauth \
  --from-address 'you@gmail.com' \
  --oauth-client-id 'YOUR_CLIENT_ID.apps.googleusercontent.com' \
  --oauth-client-secret 'YOUR_CLIENT_SECRET'

# Microsoft OAuth
email-config create \
  --name 'Microsoft-OAuth' \
  --provider microsoft-oauth \
  --from-address 'you@company.com' \
  --oauth-client-id 'YOUR_APPLICATION_ID' \
  --oauth-client-secret 'YOUR_CLIENT_SECRET' \
  --oauth-tenant-id 'YOUR_TENANT_ID'

# AWS SES
email-config create \
  --name 'AWS-SES' \
  --provider ses \
  --from-address 'verified@yourdomain.com' \
  --aws-region 'us-east-1' \
  --aws-access-key 'AKIA...' \
  --aws-secret-key 'xxx'
```

1. SMTP example uses Gmail's SMTP server with app password authentication. Use port 587 with "Use TLS" set to "true", or use port 465 with "Use SSL" set to "true".
2. SendGrid requires verified sender domain and API key
3. Gmail OAuth opens browser for authorization (tokens stored in vault)
4. Microsoft OAuth supports single and multi-tenant configurations
5. AWS SES requires IAM credentials with SES send permissions

{% hint style="info" %}
Note: For Google accounts, you need to visit <https://myaccount.google.com/apppasswords> and create an application password for mail delivery.
{% endhint %}

### email-config list

**Command:** `email-config list`

**Detail:** Display all configured email providers with their basic information.

**Examples:**

```bash
email-config list
```

**Output:**

```
Email Configurations:
  Name                Provider          From Address
  ─────────────────────────────────────────────────────────
  Gmail-OAuth         gmail-oauth       you@gmail.com
  SMTP-Office365      smtp              admin@company.com
  SendGrid-Main       sendgrid          [email protected]
```

### email-config test

**Command:** `email-config test <NAME>`

**Detail:** Test email configuration by verifying connection and authentication. Optionally send a test email.

**Parameters:**

* `<NAME>` - Configuration name to test
* `--send-to <EMAIL>` - Send test email to specified address (optional)

**Examples:**

```bash
# Test connection only (no email sent)
email-config test 'Gmail-OAuth'

# Send actual test email
email-config test 'Gmail-OAuth' --send-to 'recipient@example.com'
```

**Output (connection test):**

```
Testing connection for "Gmail-OAuth" (gmail-oauth)...
[EMAIL] Gmail OAuth connection successful: you@gmail.com
✓ Connection test successful for "Gmail-OAuth"
```

**Output (with --send-to):**

```
Testing connection for "Gmail-OAuth" (gmail-oauth)...
[EMAIL] Sending test email to recipient@example.com...
[EMAIL] Test email sent successfully
✓ Connection test successful for "Gmail-OAuth"
```

### email-config delete

**Command:** `email-config delete <NAME>`

**Detail:** Delete an email configuration from your Keeper vault.

**Parameters:**

* `<NAME>` - Configuration name to delete

**Examples:**

```bash
email-config delete 'Old-SMTP-Config'
```

### email-config update

**Command:** `email-config update <NAME> [OPTIONS]`

**Detail:** Update an existing email configuration. Accepts the same parameters as `create` command.

**Parameters:**

* `<NAME>` - Configuration name to update
* `[OPTIONS]` - Same options as `create` command

**Examples:**

```bash
# Update SMTP password
email-config update 'SMTP-Gmail' --smtp-password 'new-app-password'

# Update sender name
email-config update 'Gmail-OAuth' --from-name 'New Display Name'
```

***

## Using Email Configurations <a href="#using-email-configurations" id="using-email-configurations"></a>

Email configurations are used with commands that support email delivery.

**With record-add:**

```bash
record-add --record-type login \
  --title 'Server Access' \
  login=admin \
  password=$GEN \
  --self-destruct 24h \
  --email-config 'Gmail-OAuth' \
  --send-email 'recipient@example.com'
```

## Installation Requirements

Email provider support depends on installation method:

| Provider        | Binary | pip (basic) | pip \[email] |
| --------------- | ------ | ----------- | ------------ |
| SMTP            | ✅      | ✅           | ✅            |
| SendGrid        | ❌      | ❌           | ✅            |
| AWS SES         | ❌      | ❌           | ✅            |
| Gmail OAuth     | ❌      | ❌           | ✅            |
| Microsoft OAuth | ❌      | ❌           | ✅            |

**Install with full email support:**

```bash
pip install keepercommander[email]
```

## OAuth Interactive Flow <a href="#oauth-interactive-flow" id="oauth-interactive-flow"></a>

When creating Gmail or Microsoft OAuth configurations without `--oauth-access-token`, Commander starts an interactive authorization flow:

1. Local web server starts on port 8080 (configurable with `--oauth-port`)
2. Browser opens to provider's authorization page
3. User logs in and authorizes application
4. Browser redirects to localhost with authorization code
5. Commander exchanges code for tokens
6. Tokens are encrypted and stored in Keeper vault

**Token Management:**

* Access tokens expire after 1 hour
* Commander automatically refreshes using refresh token
* Refresh happens before sending email if token expired
* Updated tokens saved to vault automatically

***

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

**Error: "Provider is not available in the binary installation"**

Binary installations only support SMTP. Switch to pip installation:

```bash
pip install keepercommander[email]
```

**Error: "Missing required dependencies for provider"**

Install with email extras:

```bash
pip install --upgrade keepercommander[email]
```

**Error: "Interactive OAuth flow is not available on binary installation"**

Options:

1. Switch to pip installation (recommended)
2. Use SMTP provider instead
3. Provide OAuth tokens manually using `--oauth-access-token`, `--oauth-refresh-token`, `--oauth-token-expiry`

**Error: "Port 8080 already in use"**

Use different port for OAuth callback:

```bash
email-config create ... --oauth-port 9090
```

**Error: "email-config not found"**

Configuration name doesn't exist. List available configs:

```bash
email-config list
```