# Nextcloud-ConnectMail

Bulk-link IMAP/SMTP mail accounts for Nextcloud users via `occ mail:account:create`.

Intended for admins who need to link mail accounts for multiple users at once —
for example during onboarding, migration, or provisioning from an external list.

## When to use this script

The Nextcloud Mail app provides **no** REST endpoint for an admin to link an
account on behalf of another user. There is an `occ mail:account:create <userId> ...`
command, but it is positional and cumbersome for bulk work. This script wraps that
call and reads a CSV file.

Alternatives:
- **Provisioning templates** (Mail admin UI): one template per domain, no
  per-user credentials. Only works if all users share the same mail cluster.
- **Custom REST controller**: requires patching the Mail app itself.

## Requirements

- Shell access to the Nextcloud server (directly or via SSH / `docker exec`)
- `occ` executable as the web user (usually `www-data`)
- The Nextcloud Mail app installed and enabled
- `python3` on the host running the script (for RFC-4180 CSV parsing)

## Usage

```bash
OCC_CMD="docker exec -u www-data nc-dev php occ" \
  ./mail-bulk-link.sh accounts.csv
```

Classic install:

```bash
OCC_CMD="sudo -u www-data php /var/www/nextcloud/occ" \
  ./mail-bulk-link.sh accounts.csv
```

Remote via SSH:

```bash
OCC_CMD="ssh hetzner-ax42 docker exec -u www-data nc-dev php occ" \
  ./mail-bulk-link.sh accounts.csv
```

## CSV format

Header row required, column order flexible. Required columns:

```
userId,name,email,imapHost,imapPort,imapSsl,imapUser,imapPass,smtpHost,smtpPort,smtpSsl,smtpUser,smtpPass
```

Optional column: `authMethod` (`password` or `xoauth2`, defaults to `password`).

- `imapSsl` / `smtpSsl`: `ssl`, `tls`, or `none`
- Lines starting with `#` are skipped
- Quote fields containing commas per RFC 4180 (`"foo,bar"`)

See [accounts.example.csv](accounts.example.csv) for a working example.

## Limitations

- **No connection test.** The `occ` command stores blindly — invalid credentials
  are accepted silently. The user only finds out on the first sync. The REST
  route (`POST /api/accounts`) does a live IMAP/SMTP check, but only works for
  the currently logged-in user.
- **No initial mailbox sync.** The REST route triggers one; `occ` does not.
  First sync happens on the next background job run or first user login.
- **Plaintext passwords in the CSV.** They sit on disk during execution. After
  the run: `shred -u accounts.csv`. Never commit credential CSVs.

## Security

- Add `accounts.csv` (and variants) to your deployment repo's `.gitignore`
- Only run this from environments where you already hold admin rights
- For production use: pull credentials from a secrets store and generate the
  CSV on the fly in `tmpfs`

## License

AGPL-3.0-or-later (consistent with Nextcloud Mail).