SMTP & IMAP Configuration Guide

This guide covers setting up SMTP (Simple Mail Transfer Protocol) for sending emails and IMAP (Internet Message Access Protocol) for receiving emails through your own mail servers.

---

Overview

EDITH supports two types of email configurations:

Protocol	Purpose	Use Case
SMTP	Sending emails	Send through your own mail server (Gmail, Outlook, custom SMTP)
IMAP	Receiving emails	Monitor an inbox and process incoming emails via webhooks

Both support two connection types:

• Basic: Username and password authentication
• OAuth: Token-based authentication (for Gmail, Outlook, etc.)

---

SMTP Configuration

Create SMTP Configuration

Endpoint

POST /v1/smtpbasic/verify

Purpose

Creates a new SMTP configuration and verifies the connection by testing authentication with the provided credentials.

Request Body

Field	Type	Required	Description
name	string	✅ Yes	A descriptive name for this configuration (e.g., "Gmail SMTP", "Corporate Outlook")
email	string	✅ Yes	The email address associated with this SMTP account. Must be a valid email format.
connection_type	string	✅ Yes	Authentication method. Values: "basic" (username/password) or "oauth"
config_type	string	✅ Yes	Must be "smtp"
config	object	✅ Yes	SMTP server configuration details

Config Object

Field	Type	Required	Description
host	string	✅ Yes	SMTP server hostname (e.g., smtp.gmail.com, smtp.office365.com)
port	integer	✅ Yes	SMTP server port. Common ports: 587 (TLS), 465 (SSL), 25 (unencrypted)
secure	string	✅ Yes	Security protocol. Options: "Auto", "TlsWhenAvailable", "Tls", "SSL", "None"
username	string	✅ Yes	SMTP authentication username (often the email address)
password	string	✅ Yes	SMTP authentication password or app-specific password

Security Options Explained

Option	Description	Recommended Port
Auto	Automatically detect and use the best available security	Any
TlsWhenAvailable	Use TLS if server supports it, otherwise unencrypted	587
Tls	Require TLS (STARTTLS) - connection starts unencrypted, upgrades to TLS	587
SSL	Use implicit SSL/TLS - connection is encrypted from start	465
None	No encryption (not recommended)	25

Example Request - Gmail SMTP

curl -X POST https://api.edith.example.com/v1/smtpbasic/verify \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gmail SMTP",
    "email": "yourname@gmail.com",
    "connection_type": "basic",
    "config_type": "smtp",
    "config": {
      "host": "smtp.gmail.com",
      "port": 587,
      "secure": "Tls",
      "username": "yourname@gmail.com",
      "password": "your-app-specific-password"
    }
  }'

Example Request - Microsoft 365

curl -X POST https://api.edith.example.com/v1/smtpbasic/verify \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Office 365 SMTP",
    "email": "yourname@yourcompany.com",
    "connection_type": "basic",
    "config_type": "smtp",
    "config": {
      "host": "smtp.office365.com",
      "port": 587,
      "secure": "Tls",
      "username": "yourname@yourcompany.com",
      "password": "your-password"
    }
  }'

Response

{
  "success": true,
  "mailer_id": "basic_smtp_01JC3BBW8S9YGX2VNKG5MD7BTA"
}

Field	Description
success	Boolean indicating the SMTP configuration was verified and created
mailer_id	Unique identifier for this SMTP configuration. Use this when sending emails.

---

Update SMTP Configuration

Endpoint

PUT /v1/smtpbasic/update

Purpose

Updates an existing SMTP configuration and re-verifies the connection.

Request Body

All fields from create, plus:

Field	Type	Required	Description
mailer_id	string	✅ Yes	The ID of the SMTP configuration to update

Example Request

curl -X PUT https://api.edith.example.com/v1/smtpbasic/update \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mailer_id": "basic_smtp_01JC3BBW8S9YGX2VNKG5MD7BTA",
    "name": "Gmail SMTP Updated",
    "email": "yourname@gmail.com",
    "connection_type": "basic",
    "config_type": "smtp",
    "config": {
      "host": "smtp.gmail.com",
      "port": 587,
      "secure": "Tls",
      "username": "yourname@gmail.com",
      "password": "new-app-specific-password"
    }
  }'

---

Get SMTP Configuration

Endpoint

GET /v1/smtpbasic/get/{mailer_id}

Purpose

Retrieves the details of an existing SMTP configuration. Password is not returned for security.

Path Parameters

Parameter	Type	Required	Description
mailer_id	string	✅ Yes	The SMTP configuration ID

Example Request

curl -X GET https://api.edith.example.com/v1/smtpbasic/get/basic_smtp_01JC3BBW8S9YGX2VNKG5MD7BTA \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "name": "Gmail SMTP",
  "email": "yourname@gmail.com",
  "connection_type": "basic",
  "config_type": "smtp",
  "active": true,
  "config": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": "Tls",
    "username": "yourname@gmail.com"
  }
}

Note: The password is never returned in API responses for security reasons.

---

Delete SMTP Configuration

Endpoint

DELETE /v1/smtpbasic/delete/{mailer_id}

Purpose

Permanently deletes an SMTP configuration.

Example Request

curl -X DELETE https://api.edith.example.com/v1/smtpbasic/delete/basic_smtp_01JC3BBW8S9YGX2VNKG5MD7BTA \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true
}

---

IMAP Configuration

Create IMAP Configuration

Endpoint

POST /v1/imapbasic/verify

Purpose

Creates a new IMAP configuration for monitoring an email inbox. When new emails arrive, they're forwarded to your webhook endpoint.

Request Body

Field	Type	Required	Description
name	string	✅ Yes	Descriptive name for this IMAP configuration
email	string	✅ Yes	The email address of the inbox to monitor
connection_type	string	✅ Yes	Values: "basic" or "oauth"
config_type	string	✅ Yes	Must be "imap"
config	object	✅ Yes	IMAP server configuration
webhook	object	✅ Yes	Webhook configuration for incoming emails
strict_replies	boolean	No	When true, only process emails that are replies to sent emails. Default: false
include_spam	boolean	No	Include emails from spam folder. Default: false
include_trash	boolean	No	Include emails from trash folder. Default: false
include_sent	boolean	No	Include emails from sent folder. Default: false

Config Object (IMAP)

Field	Type	Required	Description
host	string	✅ Yes	IMAP server hostname (e.g., imap.gmail.com)
port	integer	✅ Yes	IMAP server port. Common: 993 (SSL), 143 (TLS)
secure	string	✅ Yes	Security protocol: "SSL" (recommended), "TLS", "None"
username	string	✅ Yes	IMAP authentication username
password	string	✅ Yes	IMAP authentication password or app-specific password

Webhook Object

Field	Type	Required	Description
webhook_url	string	✅ Yes	URL to receive incoming email notifications
event	string	✅ Yes	Must be "BASIC_IMAP"
method	string	✅ Yes	HTTP method: "GET", "POST", "PUT", "DELETE", "PATCH"
headers	object	No	Custom headers to include in webhook requests

Example Request

curl -X POST https://api.edith.example.com/v1/imapbasic/verify \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Inbox Monitor",
    "email": "support@yourcompany.com",
    "connection_type": "basic",
    "config_type": "imap",
    "config": {
      "host": "imap.gmail.com",
      "port": 993,
      "secure": "SSL",
      "username": "support@yourcompany.com",
      "password": "your-app-specific-password"
    },
    "webhook": {
      "webhook_url": "https://api.yourcompany.com/webhooks/incoming-email",
      "event": "BASIC_IMAP",
      "method": "POST",
      "headers": {
        "X-Webhook-Secret": "your-secret-key"
      }
    },
    "strict_replies": false,
    "include_spam": false,
    "include_trash": false,
    "include_sent": false
  }'

Response

{
  "success": true,
  "mailer_id": "basic_imap_01JC3BBW8S9YGX2VNKG5MD7BTA"
}

---

Folder Monitoring Options

Option	Default	Description
strict_replies	false	Only forward emails that are replies to previously sent emails. Useful for tracking conversation threads.
include_spam	false	Monitor the spam/junk folder. Enable to catch misclassified emails.
include_trash	false	Monitor the trash/deleted folder. Rarely needed.
include_sent	false	Monitor the sent folder. Useful for auditing or syncing sent emails.

---

Update IMAP Configuration

Endpoint

PUT /v1/imapbasic/update

Purpose

Updates an existing IMAP configuration and re-verifies the connection.

Request Body

All fields from create, plus:

Field	Type	Required	Description
mailer_id	string	✅ Yes	The ID of the IMAP configuration to update

Example Request

curl -X PUT https://api.edith.example.com/v1/imapbasic/update \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mailer_id": "basic_imap_01JC3BBW8S9YGX2VNKG5MD7BTA",
    "name": "Support Inbox - Updated",
    "email": "support@yourcompany.com",
    "connection_type": "basic",
    "config_type": "imap",
    "config": {
      "host": "imap.gmail.com",
      "port": 993,
      "secure": "SSL",
      "username": "support@yourcompany.com",
      "password": "new-app-password"
    },
    "webhook": {
      "webhook_url": "https://api.yourcompany.com/webhooks/v2/incoming-email",
      "event": "BASIC_IMAP",
      "method": "POST"
    },
    "strict_replies": true
  }'

---

Get IMAP Configuration

Endpoint

GET /v1/imapbasic/get/{mailer_id}

Example Request

curl -X GET https://api.edith.example.com/v1/imapbasic/get/basic_imap_01JC3BBW8S9YGX2VNKG5MD7BTA \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "name": "Support Inbox Monitor",
  "email": "support@yourcompany.com",
  "connection_type": "basic",
  "config_type": "imap",
  "active": true,
  "strict_replies": false,
  "include_spam": false,
  "include_trash": false,
  "include_sent": false,
  "config": {
    "host": "imap.gmail.com",
    "port": 993,
    "secure": "SSL",
    "username": "support@yourcompany.com"
  },
  "webhook": {
    "webhook_url": "https://api.yourcompany.com/webhooks/incoming-email",
    "event": "BASIC_IMAP",
    "method": "POST"
  }
}

---

Delete IMAP Configuration

Endpoint

DELETE /v1/imapbasic/delete/{mailer_id}

Example Request

curl -X DELETE https://api.edith.example.com/v1/imapbasic/delete/basic_imap_01JC3BBW8S9YGX2VNKG5MD7BTA \
  -H "Authorization: Bearer YOUR_TOKEN"

---

OAuth Configuration

For Gmail, Outlook, and other OAuth-enabled providers, use the OAuth endpoints for more secure token-based authentication.

Initiate OAuth Login

Endpoint

POST /v1/oauth/login

Purpose

Starts the OAuth authentication flow. Returns a URL to redirect users for authorization.

Request Body

Field	Type	Required	Description
app_id	string	✅ Yes	Your registered OAuth application ID
type	string	No	Configuration type: "smtp", "imap", or both
redirect_uri	string	No	URL to redirect after OAuth completion
state	string	No	CSRF token to verify the callback
exchange_token	boolean	No	Set true if you have a token to exchange
token	object	No	Token object for exchange flow
webhook	object	No	Webhook configuration (for IMAP)
mailer_id	string	No	Existing mailer_id to update
strict_replies	boolean	No	Only process reply emails
include_spam	boolean	No	Include spam folder
include_trash	boolean	No	Include trash folder
include_sent	boolean	No	Include sent folder

Example Request - New OAuth Flow

curl -X POST https://api.edith.example.com/v1/oauth/login \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "your-oauth-app-id",
    "type": "smtp",
    "redirect_uri": "https://yourapp.com/oauth/callback",
    "state": "random-csrf-token"
  }'

Response

{
  "success": true,
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=..."
}

Redirect the user to the returned URL to complete OAuth authorization.

---

Activate/Deactivate OAuth Configuration

Endpoint

PUT /v1/oauth/active

Purpose

Enable or disable an OAuth email configuration without deleting it.

Request Body

Field	Type	Required	Description
mailer_id	string	✅ Yes	The OAuth configuration ID
active	boolean	No	Set true to activate, false to deactivate

Example Request

curl -X PUT https://api.edith.example.com/v1/oauth/active \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mailer_id": "oauth_01JC3BBW8S9YGX2VNKG5MD7BTA",
    "active": false
  }'

---

Common SMTP/IMAP Settings

Gmail

Setting	SMTP	IMAP
Host	smtp.gmail.com	imap.gmail.com
Port	587 (TLS)	993 (SSL)
Security	Tls	SSL
Username	Full email address	Full email address
Password	App-specific password	App-specific password

Note: Gmail requires an app-specific password. Enable 2FA and generate one at Google Account Security.

Microsoft 365 / Outlook

Setting	SMTP	IMAP
Host	smtp.office365.com	outlook.office365.com
Port	587	993
Security	Tls	SSL
Username	Full email address	Full email address
Password	Account password	Account password

Yahoo Mail

Setting	SMTP	IMAP
Host	smtp.mail.yahoo.com	imap.mail.yahoo.com
Port	587	993
Security	Tls	SSL

---

Troubleshooting

SMTP Errors

Error	Cause	Solution
Authentication failed	Incorrect credentials	Verify username/password, use app-specific password
Connection refused	Wrong host or port	Check server settings
Connection timeout	Firewall blocking	Ensure port is open
TLS handshake failed	SSL/TLS mismatch	Try different security option

IMAP Errors

Error	Cause	Solution
Mailbox not found	Incorrect folder access	Verify email has inbox access
Authentication failed	Invalid credentials	Use app-specific password
Connection closed	Server timeout	Check server stability

---

Best Practices

1. Use App-Specific Passwords

   • Never use your main account password
   • Generate dedicated passwords for EDITH

2. Prefer OAuth When Available

   • More secure than basic auth
   • Automatic token refresh
   • Better audit trail

3. Use Secure Connections

   • Always use SSL or TLS
   • Avoid None security option

4. Monitor Webhook Health

   • Ensure webhook endpoints are reliable
   • Implement retry logic
   • Log incoming requests

5. Test Before Production

   • Verify configurations with test emails
   • Monitor for authentication failures