Configuration Guide

ExMailer provides multiple ways to configure your connection to a Microsoft Exchange server. Settings are applied with the following priority (highest to lowest):

1. Programmatic configuration (dictionary passed directly to ExchangeEmailer)
2. Explicit configuration file (path provided via config_path parameter)
3. Auto‑discovered configuration files (searched in predefined locations)
4. Environment variables

All configuration methods expect the same set of parameters (see table below).

Configuration Parameters

Parameter	Type	Required	Default	Description
domain	string	Yes	–	Active Directory domain (e.g., CORP, your-domain)
username	string	Yes	–	User account name (without domain, e.g., john.doe)
password	string	Yes	–	Account password
server	string	Yes	–	Exchange server hostname or IP
email_domain	string	Yes	–	Domain part of the email address (e.g., company.com)
auth_type	string	No	NTLM	Authentication method: NTLM or BASIC
save_copy	boolean	No	true	Whether to save a copy of sent emails in the Sent Items folder
exchange_build	list[int] or string	No	[15,1,2248,0]	Exchange server build version, e.g. [15, 1, 2248, 0] or "15.1.2248.0" (Exchange 2016). Invalid values fall back to the default with a warning.
timezone	string	No	system local	IANA timezone (e.g. "Asia/Tehran") attached to naive datetimes passed to meeting methods. Defaults to the system's local timezone. Invalid names raise ConfigurationError at startup.
verify_ssl	boolean	No	true	Set to false to disable TLS certificate verification (logged with a loud warning). Only for trusted internal networks.

Note on username format The full user identifier used internally is {domain}\{username}@{email_domain}. For example: CORP\john.doe@company.com

---

Method 1: Programmatic Configuration (Highest Priority)

Pass a dictionary directly when creating an ExchangeEmailer instance:

from exmailer import ExchangeEmailer

config = {
    "domain": "CORP",
    "username": "john.doe",
    "password": "your-secret-password",
    "server": "mail.company.com",
    "email_domain": "company.com",
    "auth_type": "NTLM",       # optional
    "save_copy": True          # optional
}

emailer = ExchangeEmailer(config=config)

This method overrides any file‑based or environment configuration.

---

Method 2: Configuration Files

You can store settings in a JSON or YAML file. Two approaches are supported:

A. Explicit File Path (Medium Priority)

Pass the file path using the config_path parameter:

emailer = ExchangeEmailer(config_path="/path/to/exmailer.json")

B. Auto‑discovered Files (Lower Priority)

If no explicit path is given, ExMailer looks for configuration files in the following order (first found wins):

1. ./exmailer.json
2. ./exmailer.yaml
3. ./exmailer.yml
4. ~/.config/exmailer/config.json
5. ~/.config/exmailer/exmailer.json
6. ~/.config/exmailer/config.yaml
7. ~/.config/exmailer/config.yml
8. ~/.config/exmailer/exmailer.yaml
9. ~/.config/exmailer/exmailer.yml

JSON Example (exmailer.json)

{
  "domain": "CORP",
  "username": "john.doe",
  "password": "your-password",
  "server": "mail.company.com",
  "email_domain": "company.com",
  "save_copy": true,
  "exchange_build": [15, 1, 2248, 0],
  "timezone": "UTC"
}

YAML Example (exmailer.yaml)

domain: CORP
username: john.doe
password: your-password
server: mail.company.com
email_domain: company.com
save_copy: true
# optional:
exchange_build: [15, 1, 2248, 0]
timezone: UTC

YAML does not allow trailing commas – the example above is correct.

---

Method 3: Environment Variables (Lowest Priority)

Set the following environment variables in your shell or a .env file (if you use python-dotenv or a similar loader):

EXCHANGE_DOMAIN="CORP"
EXCHANGE_USER="john.doe"
EXCHANGE_PASS="your-password"
EXCHANGE_SERVER="mail.company.com"
EXCHANGE_EMAIL_DOMAIN="company.com"
EXCHANGE_AUTH_TYPE="NTLM"      # optional, defaults to NTLM
EXCHANGE_SAVE_COPY="true"      # optional, defaults to true
EXCHANGE_VERIFY_SSL="true"     # optional, defaults to true

Boolean values accept true/false, yes/no, 1/0 (case‑insensitive).

Environment variables are the lowest-priority layer: they fill in any keys that are still missing after the dictionary and file layers have been applied. They are consulted on every load — not only when no other source is supplied.

---

Summary

Priority	Method	How to Use
1	Programmatic dictionary	ExchangeEmailer(config={...})
2	Explicit file	ExchangeEmailer(config_path="path/to/file")
3	Auto‑discovered file	Place a JSON/YAML file in one of the predefined locations
4	Environment variables	Set EXCHANGE_* variables in your environment

Choose the method that best fits your use case – programmatic for scripts, configuration files for deployment, and environment variables for containerized or ephemeral environments.