# Config files

Help text shown in-app next to each JSONC config file in the **Settings → Edit config files...** dialog. Each `##` section is matched by filename.

Comments (`//`, `/* */`) and trailing commas are allowed — mailx parses these files with a JSONC parser.

## accounts.jsonc

Defines the mail accounts mailx syncs. Stored on Google Drive so it's shared across all your devices.

```jsonc
{
  "accounts": [
    {
      "id": "gmail",                    // short, unique, lowercase — used as folder name on disk
      "name": "Bob",                    // display name used as the From: name
      "email": "bob@gmail.com",         // primary address for this account
      "defaultSend": true,              // pre-select this account in compose
      "identityDomains": ["bob.ma"],    // extra domains to recognize as "you" for reply-from detection
      "sig": {                          // signature appended to NEW messages
        "text": "Bob Frankston\nhttps://frankston.com"
      }
    },
    {
      "id": "work",
      "name": "Bob",
      "email": "bob@example.com",
      "imap": {                         // explicit IMAP/SMTP for non-auto-detected providers
        "host": "imap.example.com",
        "port": 993,
        "tls": true
      },
      "smtp": {
        "host": "smtp.example.com",
        "port": 465,
        "tls": true
      },
      "spam": "Junk"                    // override the spam folder name for this account
    }
  ]
}
```

**Fields:**

- `id` — unique, lowercase, no spaces. Changing it renames the local cache folder.
- `name` — display name used in the From: header.
- `email` — primary identity address.
- `defaultSend` — if multiple accounts, the one with `defaultSend: true` is pre-selected in compose.
- `identityDomains` — additional domains to recognize as yours (aliases, plus-addressing, forwarded domains). Used for reply auto-From detection.
- `imap` / `smtp` — server config. Omit for Gmail/Outlook/Yahoo/iCloud (auto-detected from the email domain).
- `spam` — override the spam/junk folder name if auto-detection picks the wrong one.
- `sig` — signature object. `text` is appended to NEW messages with the standard `-- ` separator (newlines preserved). Only applied to brand-new messages today; replies/forwards skip it. Future options will cover replies, per-account toggles, and a `"html": true` flag for raw HTML signatures.

Gmail accounts automatically use the Gmail REST API (no IMAP). Everything else uses IMAP via iflow-direct.

Restart mailx after editing to pick up changes.

## allowlist.jsonc

Controls which remote images/content are allowed in the message viewer without the "Show images" banner.

```jsonc
{
  "domains": [
    "github.com",                       // wildcard subdomains implied
    "stripe.com",
    "list-manage.com"                   // Mailchimp tracking — remove if you want to block
  ],
  "senders": [
    "notifications@github.com",         // full address match
    "*@anthropic.com"                   // wildcard: anything from this domain
  ]
}
```

**Fields:**

- `domains` — remote images are fetched if their host matches (with subdomain wildcarding).
- `senders` — messages from these senders get images auto-loaded regardless of image host.

Content-Security-Policy still blocks scripts regardless — this only affects image/CSS loading.

## clients.jsonc

Per-device registrations. Each mailx install writes its hostname here so you can see which devices have synced recently.

```jsonc
{
  "clients": [
    {
      "id": "desktop-abc123",           // auto-generated on first run
      "hostname": "MYPC",
      "platform": "win32",
      "lastSeen": "2026-04-18T14:00:00Z"
    }
  ]
}
```

Normally there's no reason to edit this by hand. Useful for removing stale device entries, or migrating a device to a new ID.

## config.jsonc

**Local per-machine configuration**, stored at `~/.mailx/config.jsonc`. This file is NOT synced to the cloud — it's how each machine knows where the shared config lives and which store path to use.

```jsonc
{
  "sharedDir": {
    "provider": "gdrive",               // cloud provider (only "gdrive" supported)
    "path": "mailx",                    // folder name on Google Drive
    "folderId": "1ABC...xyz"            // GDrive folder ID (API-resolved, don't edit)
  },
  "storePath": "C:/Users/Bob/.mailx/store",  // where .eml message bodies live locally

  "accountOverrides": {                 // optional: per-machine overrides to accounts.jsonc
    "work": {
      "imap": { "host": "127.0.0.1", "port": 1143 }  // e.g., tunnel on this machine only
    }
  }
}
```

**Fields:**

- `sharedDir.provider` — cloud storage. Currently only `gdrive`.
- `sharedDir.path` / `folderId` — the folder on the cloud where shared config + cache metadata live.
- `storePath` — where `.eml` bodies are cached locally. Changing requires moving existing files.
- `accountOverrides` — override parts of an account's config on this machine only (different IMAP host when behind a VPN, for example). Keys match the `id` in accounts.jsonc.

Delete and re-run `mailx -setup` to reconfigure from scratch.
