---
title: "Email Settings Module Documentation"
description: "Documentation for Email Settings"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [🎯 User Roles & Key Capabilities](#-user-roles--key-capabilities)
4. [Module Overview (Technical)](#1-module-overview-technical)
5. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
6. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
7. [Configuration Sections](#4-configuration-sections)
8. [Settings Reference](#5-settings-reference)
9. [Common Scenarios & Examples](#6-common-scenarios--examples)
10. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
11. [Limitations & Important Notes](#7-limitations--important-notes)
12. [Troubleshooting Tips](#8-troubleshooting-tips)
13. [Glossary](#9-glossary)
---

## Navigation & Access

To access the Email Settings module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Admin**.
3. Under **System Settings**, click **Email Settings** (`/admin/system-settings/email`).
4. To configure a new outgoing SMTP server profile, click the **+ Add Email Config** button.
5. To view, edit, duplicate, or send a test email through an existing profile, click on the configuration row or action icons (`/admin/system-settings/email/:id`).

---

## Screenshots & Visual Interface

### Email Settings List View
The Email Settings interface lists all registered SMTP gateway profiles (Amazon SES, SendGrid, Mailgun, Postfix) with their hostname, port, security protocol (SSL/TLS), default sender email, active status, and interactive test delivery button.
![Email Settings List](/screenshots/admin/system/email-settings-list.png)

### Email Configuration Form
The email server editor provides fine-grained settings to specify SMTP server credentials, authentication methods (Login, Plain, OAuth2), socket timeout values, default fallback sender address, and tenant isolation scopes.
![Email Configuration Form](/screenshots/admin/system/email-settings-form.png)

---

## 🎯 User Roles & Key Capabilities

The Email Settings module configures critical notification delivery pipelines for voicemail, faxes, and security alerts:

| Role | Key Capabilities & Operational Scope |
|------|--------------------------------------|
| **Super Administrator** | Configures global outbound SMTP gateways (e.g. Amazon SES, SendGrid, Postfix relay), manages TLS certificates, and sets default sender addresses. |
| **Tenant Administrator** | Establishes company-specific SMTP credentials so notifications (voicemail-to-email, missed calls) originate from the client's own corporate domain. |
| **Security & Compliance Officer** | Audits SMTP encryption protocols (enforcing TLS/SSL), validates authentication methods, and inspects delivery logs for unauthorized relays. |
| **Telephony Auditor (Read-Only)** | Reviews active SMTP hostnames, security encryption ports, and default sender addresses with credentials securely redacted. |

---

## 1. Module Overview (Technical)

### What Are Email Settings?

Email Settings is an **SMTP configuration module** that manages outgoing email server profiles. It supports multiple SMTP configurations with authentication, encryption (SSL/TLS), and includes test functionality and email delivery logs.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│              Email Settings Architecture                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Email Configuration Profiles                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Profile: Company SMTP                             │   │
│  │                                                          │   │
│  │  Basic Settings:                                         │   │
│  │  ├─ Host: smtp.company.com                              │   │
│  │  ├─ Port: 587                                           │   │
│  │  └─ TLS: Enabled                                        │   │
│  │                                                          │   │
│  │  Authentication:                                         │   │
│  │  ├─ Method: Login                                       │   │
│  │  ├─ Username: noreply@company.com                       │   │
│  │  └─ Password: ********                                  │   │
│  │                                                          │   │
│  │  Email Settings:                                         │   │
│  │  ├─ From Email: noreply@company.com                     │   │
│  │  ├─ From Name: Company PBX                              │   │
│  │  └─ Reply To: support@company.com                       │   │
│  │                                                          │   │
│  │  Status: ✓ Active, ⭐ Default                           │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Used by system                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Email Sender Service                              │   │
│  │                                                          │   │
│  │  Sends emails for:                                       │   │
│  │  ├─ Voicemail notifications                             │   │
│  │  ├─ Fax-to-email                                        │   │
│  │  ├─ System alerts                                       │   │
│  │  ├─ Password resets                                     │   │
│  │  └─ User notifications                                  │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Logged                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Email Logs                                        │   │
│  │                                                          │   │
│  │  ├─ Pending                                             │   │
│  │  ├─ Sent                                                │   │
│  │  ├─ Failed                                              │   │
│  │  └─ Bounced                                             │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

Email Settings provides **reliable email delivery**:

| Without Email Settings | With Email Settings |
|------------------------|---------------------|
| No notifications | Email alerts |
| No voicemail email | VM to email |
| No fax delivery | Fax to email |
| Unknown status | Delivery logs |

### Use Cases

1. **Voicemail Notifications**
   - Email new voicemails
   - Audio attachments

2. **System Alerts**
   - Storage warnings
   - CPU alerts
   - Security notifications

3. **Fax to Email**
   - Receive faxes as PDF
   - Email delivery

4. **User Notifications**
   - Password resets
   - Account alerts

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **Multiple Profiles** | Different SMTP servers |
| **SSL/TLS** | Secure transmission |
| **Authentication** | Login, Plain, OAuth2 |
| **Test Function** | Verify before use |
| **Email Logs** | Delivery tracking |
| **Default Profile** | Fallback configuration |

---

## 3. Module Overview (End User/Administrator)

### What Can You Do?

- Create SMTP server configurations
- Set encryption (SSL/TLS)
- Configure authentication
- Set sender information
- Test email delivery
- View email logs
- Set default profile

### Email Settings Interface

```
┌─────────────────────────────────────────────────────────────────┐
│              Email Settings                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Configure email server settings for system notifications      │
│                                                                 │
│  [+ Add Configuration]                                          │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Profile Name    │ Host              │ Status   │ Default │  │
│  ├─────────────────┼───────────────────┼──────────┼─────────┤  │
│  │ Gmail SMTP      │ smtp.gmail.com    │ ● Active │ ⭐      │  │
│  │ SendGrid        │ smtp.sendgrid.net │ ● Active │         │  │
│  │ Office365       │ smtp.office365.com│ ○ Inactive│        │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  [📋 View Logs]                                                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Add/Edit Configuration

```
┌─────────────────────────────────────────────────────────────────┐
│              Edit Configuration: Gmail SMTP                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ▼ Basic Settings                                               │
│                                                                 │
│  Profile Name: [Gmail SMTP                   ]                 │
│    Friendly name for this email configuration                   │
│                                                                 │
│  SMTP Host: [smtp.gmail.com                  ]                 │
│    SMTP server hostname or IP address                           │
│                                                                 │
│  Port: [587                                  ]                 │
│    587 for TLS, 465 for SSL, 25 for plain                       │
│                                                                 │
│  Use SSL Encryption: ☐                                         │
│    Use SSL encryption (port 465)                                │
│                                                                 │
│  Use TLS: ✓                                                    │
│    Use STARTTLS encryption (port 587)                           │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  ▼ Authentication                                               │
│                                                                 │
│  Auth Method: [Login ▼]                                        │
│    None | Login | Plain | OAuth2                                │
│                                                                 │
│  Username: [noreply@company.com              ]                 │
│    Account username or email address                            │
│                                                                 │
│  Password: [••••••••••••••••                 ]                 │
│    Password or app-specific password                            │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  ▼ Email Settings                                               │
│                                                                 │
│  From Email: [noreply@company.com            ]                 │
│    The email address that appears as sender                     │
│                                                                 │
│  From Name: [Company PBX                     ]                 │
│    The name displayed as the sender                             │
│                                                                 │
│  Reply To: [support@company.com              ]                 │
│    Where replies should be directed                             │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  ▼ Advanced Settings                                            │
│                                                                 │
│  Connection Timeout: [60000     ] ms                           │
│  Greeting Timeout: [30000       ] ms                           │
│  Socket Timeout: [60000         ] ms                           │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  ▼ Status Settings                                              │
│                                                                 │
│  Enable Profile: ✓                                             │
│    Enable this configuration for sending emails                 │
│                                                                 │
│  Set as Default: ✓                                             │
│    Use this as the default configuration                        │
│                                                                 │
│  [Test Configuration] [Save] [Cancel]                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Test Configuration

```
┌─────────────────────────────────────────────────────────────────┐
│              Test Email Configuration                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Enter an email address to send a test message                  │
│                                                                 │
│  Test Email Address: [admin@company.com      ]                 │
│                                                                 │
│  [Send Test]                                                    │
│                                                                 │
│  ✓ Test Successful                                             │
│  Test email sent successfully                                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Email Logs

```
┌─────────────────────────────────────────────────────────────────┐
│              Email Logs                                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  View email sending history and status                          │
│                                                                 │
│  Filters:                                                       │
│  Status: [All statuses ▼] From: [         ] To: [         ]   │
│                                                                 │
│  [🔍 Search logs...]                                            │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Date       │ To                │ Subject      │ Status   │  │
│  ├────────────┼───────────────────┼──────────────┼──────────┤  │
│  │ 2025-01-16 │ user@company.com  │ New Voicemail│ ● Sent   │  │
│  │ 2025-01-16 │ admin@company.com │ System Alert │ ● Sent   │  │
│  │ 2025-01-15 │ bad@invalid.com   │ Notification │ ✗ Failed │  │
│  │ 2025-01-15 │ user@company.com  │ Fax Received │ ● Sent   │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **Test Before Use**: Always test configuration before going live.

> [!TIP]
> **App Passwords**: Use app-specific passwords for Gmail/Office365.

> [!NOTE]
> **Password Storage**: Passwords are stored encrypted.

---

## 4. Configuration Sections

### Basic Settings

| Field | Description |
|-------|-------------|
| **Profile Name** | Identifier |
| **SMTP Host** | Server address |
| **Port** | SMTP port |
| **Use SSL** | SSL encryption (465) |
| **Use TLS** | STARTTLS (587) |

### Authentication

| Field | Description |
|-------|-------------|
| **Auth Method** | None, Login, Plain, OAuth2 |
| **Username** | Login username |
| **Password** | Login password |

### Email Settings

| Field | Description |
|-------|-------------|
| **From Email** | Sender address |
| **From Name** | Sender display name |
| **Reply To** | Reply destination |

### Advanced Settings

| Field | Description |
|-------|-------------|
| **Connection Timeout** | Connect wait (ms) |
| **Greeting Timeout** | Server greeting wait (ms) |
| **Socket Timeout** | Operation wait (ms) |

### Status Settings

| Field | Description |
|-------|-------------|
| **Enable Profile** | Active/Inactive |
| **Set as Default** | System default |

---

## 5. Settings Reference

### Common SMTP Servers

| Provider | Host | Port | Encryption |
|----------|------|------|------------|
| Gmail | smtp.gmail.com | 587 | TLS |
| Office 365 | smtp.office365.com | 587 | TLS |
| SendGrid | smtp.sendgrid.net | 587 | TLS |
| Amazon SES | email-smtp.{region}.amazonaws.com | 587 | TLS |
| Mailgun | smtp.mailgun.org | 587 | TLS |

### Port Guide

| Port | Encryption | Use Case |
|------|------------|----------|
| 25 | None | Legacy (not recommended) |
| 465 | SSL | Implicit SSL |
| 587 | TLS | STARTTLS (recommended) |
| 2525 | TLS | Alternative TLS |

### Email Log Statuses

| Status | Meaning |
|--------|---------|
| **Pending** | Queued for delivery |
| **Sent** | Successfully delivered |
| **Failed** | Delivery failed |
| **Bounced** | Recipient rejected |

---

## 6. Common Scenarios & Examples

### Scenario 1: Gmail SMTP

1. Add Configuration
2. Name = "Gmail SMTP"
3. Host = smtp.gmail.com
4. Port = 587
5. Enable TLS
6. Auth = Login
7. Username = your@gmail.com
8. Password = App Password (not regular password)
9. Test and Save

### Scenario 2: Office 365

1. Add Configuration
2. Name = "Office365"
3. Host = smtp.office365.com
4. Port = 587
5. Enable TLS
6. Auth = Login
7. Use Microsoft account credentials
8. Test and Save

### Scenario 3: SendGrid

1. Add Configuration
2. Name = "SendGrid"
3. Host = smtp.sendgrid.net
4. Port = 587
5. Enable TLS
6. Auth = Login
7. Username = apikey
8. Password = SendGrid API Key
9. Test and Save

### Scenario 4: Multiple Profiles

1. Create primary SMTP (Gmail)
2. Set as Default
3. Create backup SMTP (SendGrid)
4. Keep as secondary
5. Both profiles available

---

## Model Context Protocol (MCP) AI Integration

The Ring2All PBX platform provides Model Context Protocol (MCP) tools for inspecting outgoing SMTP server configurations and deliverability settings.

### MCP Tools Reference

| Tool Name | Operation | Description | Risk Level |
|-----------|-----------|-------------|------------|
| `get_email_settings` | Read | Retrieves outgoing SMTP configuration (host, port, TLS security, sender address) with passwords redacted. | Low |

### JSON Schema Definitions

#### `get_email_settings`
```json
{
  "name": "get_email_settings",
  "description": "Retrieves outgoing SMTP email server configuration with passwords securely redacted.",
  "parameters": {
    "type": "object",
    "properties": {}
  }
}
```

### Natural Language Prompt Examples

#### English
- *"What SMTP host and port are configured for outgoing PBX notifications?"*
- *"Check if TLS encryption is enabled on the outgoing mail server."*
- *"What sender email address is used when dispatching voicemail-to-email notifications?"*

#### Spanish
- *"¿Cuál es el servidor SMTP y puerto configurado para enviar correos?"*
- *"Verifica si el servidor de correo saliente tiene habilitado cifrado TLS."*
- *"Consulta la dirección de remitente ('From') configurada para las alertas del sistema."*

### Enterprise Safeguards & Guardrails
1. **Password Redaction**: SMTP passwords and API secrets are strictly redacted and replaced with security masks (`[PROTECTED]`).
2. **Read-Only Inspection**: AI assistants can verify server readiness without exposing mail dispatch endpoints to unauthorized mass email spam.

---

## 7. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **App Passwords**: Gmail/Office365 require app-specific passwords.

> [!NOTE]
> **Rate Limits**: SMTP providers have sending limits.

> [!WARNING]
> **SPF/DKIM**: Configure DNS for best deliverability.

### Best Practices

1. **App Passwords**: Use for Gmail/Microsoft
2. **TLS**: Always use encryption
3. **Test First**: Verify before production
4. **Monitor Logs**: Check for failures
5. **Backup Profile**: Have secondary SMTP

### Gmail Requirements

| Requirement | Action |
|-------------|--------|
| 2FA Enabled | Enable two-factor auth |
| App Password | Generate app-specific password |
| Less Secure Apps | Not needed with app passwords |

---

## 8. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| Connection timeout | Wrong host/port | Verify settings |
| Auth failed | Wrong credentials | Check username/password |
| TLS error | Wrong encryption | Match port to encryption |
| Test fails | Firewall blocking | Check outbound port |

### Test SMTP Connection

```bash
# Test port connectivity
telnet smtp.gmail.com 587

# Test with OpenSSL
openssl s_client -starttls smtp -connect smtp.gmail.com:587
```

### Check Logs

```sql
SELECT 
  recipient_email,
  subject,
  status,
  error_message,
  sent_at
FROM public.email_logs
ORDER BY sent_at DESC
LIMIT 20;
```

---

## 9. Glossary

| Term | Definition |
|------|------------|
| **SMTP** | Simple Mail Transfer Protocol |
| **TLS** | Transport Layer Security |
| **SSL** | Secure Sockets Layer |
| **STARTTLS** | TLS upgrade command |
| **App Password** | Single-use app credential |
| **SPF** | Sender Policy Framework |

---

*Documentation last updated: January 2026*