EmailOS File Config

EmailOS can read send-related defaults from repo-local JSON, TOML, and env files.

This is intended for values that are safe to commit, such as:

• default sender address
• default sender display name
• default signature source
• sent-mail project domain filters

Keep secrets such as passwords and tokens in env files or global config, not in emailos.json or emailos.toml.

Repo-Local Project Config

EmailOS reads the nearest parent emailos.json or emailos.toml for project-scoped send, sent, and search behavior, starting in the current directory and walking upward. If both files exist in the same directory, emailos.json wins, with a sibling emailos.toml still able to supply max_body_words, sent_to_domain, and ignore_domains when those fields are absent from emailos.json.

Supported fields:

{
  "email_address": "[email protected]",
  "from_address": "[email protected]",
  "from_name": "My Name",
  "signature": "https://example.com/email-signature.html",
  "picture": "/path/to/profile-image.png",
  "media": [
    "assets/photo.png",
    "/path/to/document.pdf"
  ],
  "local_storage": false,
  "max_body_words": 50,
  "sent_to_domain": "example.com",
  "ignore_domains": ["github.com"]
}

The same values can be written as emailos.toml:

email_address = "[email protected]"
from_address = "[email protected]"
from_name = "My Name"
signature = "https://example.com/email-signature.html"
picture = "/path/to/profile-image.png"
media = [
  "assets/photo.png",
  "/path/to/document.pdf",
]
local_storage = false
max_body_words = 50
sent_to_domain = "example.com"
ignore_domains = ["github.com"]

Field mapping:

• email_address -> MAILOS_EMAIL_ADDRESS
• from_address -> MAILOS_FROM_EMAIL
• from_name -> MAILOS_FROM_NAME
• signature -> MAILOS_SIGNATURE
• picture -> MAILOS_PICTURE
• media -> MAILOS_MEDIA
• local_storage -> folder-specific .email/ storage when set to true
• max_body_words -> maximum non-signature body words allowed by mailos send
• sent_to_domain -> default recipient domain filter for mailos sent and all mailos search commands
• ignore_domains -> sender domains excluded from mailos search

Notes:

• signature may be inline text, a local file path, or an http/https URL.
• media may be a string or an array of local file paths in emailos.json, or an array of local file paths in emailos.toml. Relative paths are resolved from the directory containing the project config file. Use the mailos send --media flag for one-off media attachments that should not be saved in project config.
• Local .email/ storage is disabled by default, even if a .email/ directory already exists. Set local_storage = true to store MailOS drafts/sent exports under .email/ next to the project config. MailOS adds that folder to the repository's local .git/info/exclude, not .gitignore, so files stay searchable locally without appearing in Git status.
• max_body_words is checked before signatures are appended, so default signatures do not count toward the limit.
• sent_to_domain = "example.com" scopes mailos sent and all mailos search commands to emails addressed to that domain unless an explicit --to or --to-domain filter is supplied.
• ignore_domains = ["github.com"] excludes messages from senders at those domains from mailos search; command-line --exclude-domains values are added to the project list.
• If email_address is omitted, EmailOS falls back to from_address when populating MAILOS_EMAIL_ADDRESS.
• from_address in project config is authoritative for send commands and overrides any existing MAILOS_FROM_EMAIL value.

Set the sent-domain filter from the CLI:

mailos configure --sent-to-domain example.com

Env Files

EmailOS also reads env-style config files for send defaults.

Supported locations:

• ./.env.mailos
• ./.env
• ~/.email/.env

Example ./.env.mailos:

MAILOS_EMAIL_ADDRESS=[email protected]
MAILOS_FROM_NAME="My Name"
MAILOS_SIGNATURE="https://example.com/email-signature.html"
MAILOS_MEDIA="/path/to/photo.png:/path/to/document.pdf"

Resolution Order

For mailos send, values are resolved in this order:

1. Existing exported environment variables
2. ./.env.mailos
3. ./.env
4. nearest parent emailos.json or emailos.toml (from_address overrides MAILOS_FROM_EMAIL)
5. ~/.email/.env

Most values only fill unset variables, so earlier sources win. from_address is the exception: project config deliberately controls the outgoing sender for that project.

Send Defaults

mailos send uses the resolved values to determine defaults such as:

• sender account email
• From address
• From display name
• signature source
• profile image
• media attachments

If MAILOS_EMAIL_ADDRESS is available from env or project config, mailos send uses it before falling back to local ./.email/config.json account selection.

When project config sets from_address, mailos send --from ... and mailos send --account ... cannot change the project send account or outgoing From address. The CLI warns and keeps the project sender policy; update the project config file to change the sender.

Diagnostics and Shell Export

Use these commands from the same directory where you will send:

mailos whoami
mailos config --values
mailos env

mailos whoami and mailos config --values show the resolved send values and their source. mailos env includes the nearest parent project config path, the resolved MAILOS_FROM_EMAIL, and a reminder that MAILOS_FROM_EMAIL controls the outgoing From address while --account selects credentials.

Some AI clients and shells only inspect actual process environment variables with commands such as printenv. Parent project config values are resolved by MailOS at runtime, so those tools will not see them until you export them:

eval "$(mailos env --export)"

mailos env --export prints shell-safe exports for non-secret send values only:

export MAILOS_EMAIL_ADDRESS='[email protected]'
export MAILOS_FROM_EMAIL='[email protected]'
export MAILOS_FROM_NAME='My Name'

It does not export secrets such as MAILOS_APP_PASSWORD.

Recommended Split

Use emailos.json or emailos.toml for commit-safe team defaults:

• email_address
• from_address
• from_name
• signature

Use env files for local or sensitive values:

• MAILOS_APP_PASSWORD
• APP_PASSWORD
• API keys
• machine-specific overrides

Global Profiles

Reusable project defaults can be saved on the user's machine as TOML profiles in ~/.email/configs.

Save the nearest project config globally:

mailos env --save-profile work

Apply that profile to any folder:

cd ~/work/client-folder
mailos env work

This makes ./emailos.toml a symlink to ~/.email/configs/work.toml, so globally managed account defaults update everywhere. Use mailos env work --copy to write a folder-local snapshot instead. If there is no exact profile match, MailOS can match a normalized shorthand such as prod to production and asks for y/N confirmation before applying it. Use mailos env list to see saved profile names and sender values together.

Applied profiles are added to the current repository's local .git/info/exclude by default so generated per-folder config stays out of code changes. Use mailos env work --no-exclude to leave Git excludes unchanged.

Example Setup

emailos.json:

{
  "email_address": "[email protected]",
  "from_address": "[email protected]",
  "from_name": "My Name",
  "signature": "https://example.com/email-signature.html",
  "media": [
    "assets/photo.png"
  ],
  "local_storage": true
}

Or emailos.toml:

email_address = "[email protected]"
from_address = "[email protected]"
from_name = "My Name"
signature = "https://example.com/email-signature.html"
media = [
  "assets/photo.png",
]
local_storage = true

Optional local override in ./.env.mailos:

MAILOS_FROM_NAME="My Name"

Dry-run verification:

mailos send --to [email protected] --subject "Config check" --body "Testing config loading" --dry-run