Email Configuration Commands

Manage email provider configurations for sending one-time shares and notifications.

Overview

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]

Note: Binary installations and basic pip installations pip install keepercommander only support SMTP.

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 command

  • Rotating a password and sending a one-time share with the pam action rotate command

  • Automating the rotation and delivery of new employee credentials with the credential-provision command

Email Configuration Commands

create

Create new email provider configuration

list

List all configured email providers

test

Test email configuration

delete

Delete email configuration

update

Update existing email configuration

email-config create

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, aws-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 <ON|OFF> - Enable TLS (default: ON)

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-id <KEY> - AWS access key ID

  • --aws-secret-access-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:

# SMTP with Gmail
email-config create \
  --name 'SMTP-Gmail' \
  --provider smtp \
  --from-address '[email protected]' \
  --from-name 'Your Name' \
  --smtp-host 'smtp.gmail.com' \
  --smtp-port 587 \
  --smtp-use-tls 'true' \
  --smtp-use-ssl 'false' \
  --smtp-username '[email protected]' \
  --smtp-password 'app-password'

# SendGrid
email-config create \
  --name 'SendGrid' \
  --provider sendgrid \
  --from-address '[email protected]' \
  --sendgrid-api-key 'SG.xxx'

# Gmail OAuth (interactive flow)
email-config create \
  --name 'Gmail-OAuth' \
  --provider gmail-oauth \
  --from-address '[email protected]' \
  --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 '[email protected]' \
  --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 aws-ses \
  --from-address '[email protected]' \
  --aws-region 'us-east-1' \
  --aws-access-key-id 'AKIA...' \
  --aws-secret-access-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

Note: For Google accounts, you need to visit https://myaccount.google.com/apppasswords and create an application password for mail delivery.

email-config list

Command: email-config list

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

Examples:

email-config list

Output:

Email Configurations:
  Name                Provider          From Address
  ─────────────────────────────────────────────────────────
  Gmail-OAuth         gmail-oauth       [email protected]
  SMTP-Office365      smtp              [email protected]
  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:

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

# Send actual test email
email-config test 'Gmail-OAuth' --send-to '[email protected]'

Output (connection test):

Testing connection for "Gmail-OAuth" (gmail-oauth)...
[EMAIL] Gmail OAuth connection successful: [email protected]
✓ Connection test successful for "Gmail-OAuth"

Output (with --send-to):

Testing connection for "Gmail-OAuth" (gmail-oauth)...
[EMAIL] Sending test email to [email protected]...
[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:

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:

# 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

Email configurations are used with commands that support email delivery.

With record-add:

record-add --record-type login \
  --title 'Server Access' \
  login=admin \
  password=$GEN \
  --self-destruct 24h \
  --email-config 'Gmail-OAuth' \
  --send-email '[email protected]'

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:

pip install keepercommander[email]

OAuth Interactive Flow

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

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

Binary installations only support SMTP. Switch to pip installation:

pip install keepercommander[email]

Error: "Missing required dependencies for provider"

Install with email extras:

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:

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

Error: "email-config not found"

Configuration name doesn't exist. List available configs:

email-config list
PreviousAutomation CommandsNextDomain Reservation Commands

Last updated

Was this helpful?