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

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 during mailos send, starting in the current directory and walking upward. If both files exist in the same directory, emailos.json wins.

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
}

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

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

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.
• 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.

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 writes ./emailos.toml from ~/.email/configs/work.toml. 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://gist.githubusercontent.com/anduimagui/e3ca5801a9d8ea7f000afee609ceab50/raw/2e2ec763ae71015f3c8bc289dab269f5d306aaa8/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://gist.githubusercontent.com/anduimagui/e3ca5801a9d8ea7f000afee609ceab50/raw/2e2ec763ae71015f3c8bc289dab269f5d306aaa8/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