feat(mail): mailaccount write endpoints — add / update / delete

CHANGELOG.md

@@ -96,6 +96,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Mail account write endpoints (#114, #13 write slice):
+  `kasapi-cli mail accounts add <address> --password <pw> [field flags]`,
+  `… update <mail-login> [field flags]` and
+  `… delete <mail-login>` wire `add_mailaccount` / `update_mailaccount`
+  / `delete_mailaccount`. `update` and `delete` are gated by the #109
+  confirmation prompt; `add` is reversible and not prompted. All three
+  honour `--dry-run` (#132) and emit a #131 audit record; the password
+  is redacted in both. `add` splits the address on the last `@` into
+  the `local_part` / `domain_part` KAS expects and takes no
+  `mail_login` — KAS generates the login (e.g. `m0000001`) and echoes
+  it in `ReturnInfo`, which the command prints. The Y/N/text toggles
+  and XLIST folder names default to the KAS API's own defaults, so a
+  bare `add <address> --password <pw>` is a complete create. `update`
+  sends only the explicitly-set flags (keyed on cobra `Changed`), adds
+  the `--active` (`is_active`) toggle, and its `--password` maps to
+  `mail_new_password` (the `_new_password` split the
+  database/ftpuser/sambauser slices carry) rather than the add-only
+  `mail_password`. `responder` is passed through verbatim ("N", "Y" or
+  a `<start>|<end>` timestamp range). `delete_mailaccount`'s prompt
+  uses the louder verb "permanently delete" — it drops the mailbox and
+  every message in it (the same data-loss emphasis as
+  `delete_database`).
+
 - `database.InProgressFalse` / `database.InProgressTrue` package
   constants for the literal `"FALSE"` / `"TRUE"` strings the KAS API
   uses to encode the async-write flag, so mapping code and tests

docs/cli/kasapi-cli_mail.md

@@ -29,7 +29,7 @@ Inspect mail accounts and filters; inspect and manage forwards and mailing lists
 ### SEE ALSO
 
 * [kasapi-cli](kasapi-cli.md)	 - Command-line client for the All-Inkl KAS API
-* [kasapi-cli mail accounts](kasapi-cli_mail_accounts.md)	 - Inspect mail accounts (get_mailaccounts)
+* [kasapi-cli mail accounts](kasapi-cli_mail_accounts.md)	 - Inspect and manage mail accounts (get/add/update/delete_mailaccount)
 * [kasapi-cli mail filters](kasapi-cli_mail_filters.md)	 - Inspect mail standard filters (get_mailstandardfilter)
 * [kasapi-cli mail forwards](kasapi-cli_mail_forwards.md)	 - Inspect and manage mail forwards (get/add/update/delete_mailforward)
 * [kasapi-cli mail lists](kasapi-cli_mail_lists.md)	 - Inspect and manage mailing lists (get/add/update/delete_mailinglist)

docs/cli/kasapi-cli_mail_accounts.md

@@ -1,6 +1,6 @@
 ## kasapi-cli mail accounts
 
-Inspect mail accounts (get_mailaccounts)
+Inspect and manage mail accounts (get/add/update/delete_mailaccount)
 
 ### Options
 
@@ -29,6 +29,9 @@ Inspect mail accounts (get_mailaccounts)
 ### SEE ALSO
 
 * [kasapi-cli mail](kasapi-cli_mail.md)	 - Inspect mail accounts and filters; inspect and manage forwards and mailing lists
+* [kasapi-cli mail accounts add](kasapi-cli_mail_accounts_add.md)	 - Create a mail account (add_mailaccount; the login is generated by KAS)
+* [kasapi-cli mail accounts delete](kasapi-cli_mail_accounts_delete.md)	 - Permanently delete a mail account and all messages in it (delete_mailaccount)
 * [kasapi-cli mail accounts get](kasapi-cli_mail_accounts_get.md)	 - Show details for a single mail account (get_mailaccounts with mail_login)
 * [kasapi-cli mail accounts list](kasapi-cli_mail_accounts_list.md)	 - List all mail accounts (get_mailaccounts)
+* [kasapi-cli mail accounts update](kasapi-cli_mail_accounts_update.md)	 - Replace mutable fields of a mail account (update_mailaccount)
 

docs/cli/kasapi-cli_mail_accounts_add.md

@@ -0,0 +1,62 @@
+## kasapi-cli mail accounts add
+
+Create a mail account (add_mailaccount; the login is generated by KAS)
+
+### Synopsis
+
+Create a mail account via add_mailaccount. The address is split on the
+last '@' into the local_part / domain_part KAS expects, and KAS
+generates the mail login (e.g. m0000001), which the command prints on
+success.
+
+The Y/N/text toggles and XLIST folder names default to the KAS API's
+own defaults, so "accounts add info@example.com --password <pw>" is a
+complete create; override any field with its flag.
+
+```
+kasapi-cli mail accounts add <address> --password <pw> [field flags] [flags]
+```
+
+### Options
+
+```
+      --allow-nets string               restrict access to these IP/CIDR networks (empty = no restriction)
+      --copy-address string             BCC copy recipient address(es)
+  -h, --help                            help for add
+      --password string                 initial mailbox password (required)
+      --responder string                auto-responder: "N", "Y", or a "<start>|<end>" timestamp range (default "N")
+      --responder-content-type string   auto-responder body format (html|text) (default "text")
+      --responder-displayname string    auto-responder sender display name
+      --responder-text string           auto-responder message body
+      --sender-alias string             permitted FROM alias address(es)
+      --webmail-autologin string        allow KAS-to-webmail auto-login (Y|N) (default "Y")
+      --xlist-archiv string             XLIST archive folder name (default "Archive")
+      --xlist-drafts string             XLIST drafts folder name (default "Drafts")
+      --xlist-enabled string            enable XLIST special-folder mapping (Y|N) (default "Y")
+      --xlist-sent string               XLIST sent-items folder name (default "Sent")
+      --xlist-spam string               XLIST spam folder name (default "Spam")
+      --xlist-trash string              XLIST trash folder name (default "Trash")
+```
+
+### Options inherited from parent commands
+
+```
+      --audit-log string                 append a JSON-Lines audit record for each write action to this file (also KAS_AUDIT_LOG); a logfmt line always goes to stderr regardless
+      --auth-data string                 KAS auth data (overrides config and KAS_AUTHDATA)
+      --auth-type string                 KAS auth strategy: 'plain' = send password on each KasApi call (no KasAuth, no 2FA support); 'session' = bootstrap via KasAuth and reuse the credential token. Overrides config and KAS_AUTHTYPE.
+      --config string                    path to the kasapi-cli config file (overrides the default location)
+      --dry-run                          preview a destructive command's KAS request (action + redacted parameters) and exit 0 without dispatching or prompting; honours --output
+      --login string                     KAS login (overrides config and KAS_LOGIN)
+      --otp string                       2FA one-time PIN — sent to KasAuth as session_2fa during the credential-token bootstrap. Requires auth_type=session; the KAS API does not document 2FA on direct kas_auth_type=plain calls.
+  -o, --output string                    output format: json|yaml|table (default table)
+      --profile string                   profile to select from the config file (overrides default_profile)
+      --session-lifetime int             session_lifetime in seconds passed to KasAuth (1..30000); 0 keeps the server default. Requires auth_type=session.
+      --session-update-lifetime string   session_update_lifetime passed to KasAuth ('Y' = sliding window, 'N' = fixed). Empty omits the parameter. Requires auth_type=session.
+  -v, --verbose                          enable verbose logging on stderr
+  -y, --yes                              skip confirmation prompts on destructive operations
+```
+
+### SEE ALSO
+
+* [kasapi-cli mail accounts](kasapi-cli_mail_accounts.md)	 - Inspect and manage mail accounts (get/add/update/delete_mailaccount)
+

docs/cli/kasapi-cli_mail_accounts_delete.md

@@ -0,0 +1,36 @@
+## kasapi-cli mail accounts delete
+
+Permanently delete a mail account and all messages in it (delete_mailaccount)
+
+```
+kasapi-cli mail accounts delete <mail-login> [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for delete
+```
+
+### Options inherited from parent commands
+
+```
+      --audit-log string                 append a JSON-Lines audit record for each write action to this file (also KAS_AUDIT_LOG); a logfmt line always goes to stderr regardless
+      --auth-data string                 KAS auth data (overrides config and KAS_AUTHDATA)
+      --auth-type string                 KAS auth strategy: 'plain' = send password on each KasApi call (no KasAuth, no 2FA support); 'session' = bootstrap via KasAuth and reuse the credential token. Overrides config and KAS_AUTHTYPE.
+      --config string                    path to the kasapi-cli config file (overrides the default location)
+      --dry-run                          preview a destructive command's KAS request (action + redacted parameters) and exit 0 without dispatching or prompting; honours --output
+      --login string                     KAS login (overrides config and KAS_LOGIN)
+      --otp string                       2FA one-time PIN — sent to KasAuth as session_2fa during the credential-token bootstrap. Requires auth_type=session; the KAS API does not document 2FA on direct kas_auth_type=plain calls.
+  -o, --output string                    output format: json|yaml|table (default table)
+      --profile string                   profile to select from the config file (overrides default_profile)
+      --session-lifetime int             session_lifetime in seconds passed to KasAuth (1..30000); 0 keeps the server default. Requires auth_type=session.
+      --session-update-lifetime string   session_update_lifetime passed to KasAuth ('Y' = sliding window, 'N' = fixed). Empty omits the parameter. Requires auth_type=session.
+  -v, --verbose                          enable verbose logging on stderr
+  -y, --yes                              skip confirmation prompts on destructive operations
+```
+
+### SEE ALSO
+
+* [kasapi-cli mail accounts](kasapi-cli_mail_accounts.md)	 - Inspect and manage mail accounts (get/add/update/delete_mailaccount)
+

docs/cli/kasapi-cli_mail_accounts_get.md

@@ -32,5 +32,5 @@ kasapi-cli mail accounts get <mail-login> [flags]
 
 ### SEE ALSO
 
-* [kasapi-cli mail accounts](kasapi-cli_mail_accounts.md)	 - Inspect mail accounts (get_mailaccounts)
+* [kasapi-cli mail accounts](kasapi-cli_mail_accounts.md)	 - Inspect and manage mail accounts (get/add/update/delete_mailaccount)
 

docs/cli/kasapi-cli_mail_accounts_list.md

@@ -32,5 +32,5 @@ kasapi-cli mail accounts list [flags]
 
 ### SEE ALSO
 
-* [kasapi-cli mail accounts](kasapi-cli_mail_accounts.md)	 - Inspect mail accounts (get_mailaccounts)
+* [kasapi-cli mail accounts](kasapi-cli_mail_accounts.md)	 - Inspect and manage mail accounts (get/add/update/delete_mailaccount)
 

docs/cli/kasapi-cli_mail_accounts_update.md

@@ -0,0 +1,52 @@
+## kasapi-cli mail accounts update
+
+Replace mutable fields of a mail account (update_mailaccount)
+
+```
+kasapi-cli mail accounts update <mail-login> [field flags] [flags]
+```
+
+### Options
+
+```
+      --active string                   mailbox status (Y|N)
+      --allow-nets string               restrict access to these IP/CIDR networks
+      --copy-address string             BCC copy recipient address(es)
+  -h, --help                            help for update
+      --password string                 replacement mailbox password (sent as mail_new_password)
+      --responder string                auto-responder: "N", "Y", or a "<start>|<end>" timestamp range
+      --responder-content-type string   auto-responder body format (html|text)
+      --responder-displayname string    auto-responder sender display name
+      --responder-text string           auto-responder message body
+      --sender-alias string             permitted FROM alias address(es)
+      --webmail-autologin string        allow KAS-to-webmail auto-login (Y|N)
+      --xlist-archiv string             XLIST archive folder name
+      --xlist-drafts string             XLIST drafts folder name
+      --xlist-enabled string            enable XLIST special-folder mapping (Y|N)
+      --xlist-sent string               XLIST sent-items folder name
+      --xlist-spam string               XLIST spam folder name
+      --xlist-trash string              XLIST trash folder name
+```
+
+### Options inherited from parent commands
+
+```
+      --audit-log string                 append a JSON-Lines audit record for each write action to this file (also KAS_AUDIT_LOG); a logfmt line always goes to stderr regardless
+      --auth-data string                 KAS auth data (overrides config and KAS_AUTHDATA)
+      --auth-type string                 KAS auth strategy: 'plain' = send password on each KasApi call (no KasAuth, no 2FA support); 'session' = bootstrap via KasAuth and reuse the credential token. Overrides config and KAS_AUTHTYPE.
+      --config string                    path to the kasapi-cli config file (overrides the default location)
+      --dry-run                          preview a destructive command's KAS request (action + redacted parameters) and exit 0 without dispatching or prompting; honours --output
+      --login string                     KAS login (overrides config and KAS_LOGIN)
+      --otp string                       2FA one-time PIN — sent to KasAuth as session_2fa during the credential-token bootstrap. Requires auth_type=session; the KAS API does not document 2FA on direct kas_auth_type=plain calls.
+  -o, --output string                    output format: json|yaml|table (default table)
+      --profile string                   profile to select from the config file (overrides default_profile)
+      --session-lifetime int             session_lifetime in seconds passed to KasAuth (1..30000); 0 keeps the server default. Requires auth_type=session.
+      --session-update-lifetime string   session_update_lifetime passed to KasAuth ('Y' = sliding window, 'N' = fixed). Empty omits the parameter. Requires auth_type=session.
+  -v, --verbose                          enable verbose logging on stderr
+  -y, --yes                              skip confirmation prompts on destructive operations
+```
+
+### SEE ALSO
+
+* [kasapi-cli mail accounts](kasapi-cli_mail_accounts.md)	 - Inspect and manage mail accounts (get/add/update/delete_mailaccount)
+

docs/usage/destructive-writes.md

@@ -30,8 +30,8 @@ the deviations.
   sinks.
 - Subcommands whose KAS action generates the login server-side
   (`add_ftpuser`, `add_sambauser`, `add_ddnsuser`, `add_database`,
-  `add_mailinglist`, `add_mailforward`) print the generated identifier
-  on success.
+  `add_mailinglist`, `add_mailforward`, `add_mailaccount`) print the
+  generated identifier on success.
 
 ## Per-slice deviations
 
@@ -44,6 +44,7 @@ the deviations.
 | [`sambausers`](https://github.com/chmmou/kasapi-cli/issues/120) | Password key splits between actions: `--password` → `samba_password` on add, `samba_new_password` on update. Note: the KAS docs wrongly list `samba_new_password` for the create call; the captured fixture confirms the real key is `samba_password`. |
 | [`databases`](https://github.com/chmmou/kasapi-cli/issues/122) | **Louder delete prompt**: `delete_database` uses the verb `"permanently delete"` (vs the bare `"delete"` every other slice uses) because the action drops the database AND every row in it — the loudest data-loss surface of the v0.2.0 write phase. Password key splits between actions: `--password` → `database_password` on add, `database_new_password` on update. `--allowed-hosts` is **optional**: an empty value is the KAS API's documented "any host may connect" wildcard, sent verbatim on the wire. |
 | [`ddnsusers`](https://github.com/chmmou/kasapi-cli/issues/121) | **No `_new_password` split**: `--password` maps to `dyndns_password` on both `add` and `update`. `update_ddnsuser` accepts `--target-ipv4` / `--target-ipv6` instead of `add`'s legacy `--target-ip`; the ipv4/ipv6 keys are undocumented in the KAS API docs but verified to work against the live system (the captured update request fixture is authoritative). |
+| [`mail accounts`](https://github.com/chmmou/kasapi-cli/issues/114) | **Louder delete prompt**: `delete_mailaccount` uses `"permanently delete"` (shared with `databases`) — it drops the mailbox AND every message in it. `add` splits the address on the last `@` into `local_part` / `domain_part`; `update`/`delete` address the account by its generated `mail_login`. Password key splits between actions: `--password` → `mail_password` on add, `mail_new_password` on update. `add`'s Y/N/text toggles and XLIST folder names default to the KAS API's own defaults; `--responder` is passed through verbatim (`N`, `Y`, or a `<start>\|<end>` timestamp range). |
 
 ## The contract
 

internal/cli/export_test.go

@@ -34,8 +34,13 @@ var RevokeSession = revokeSession
 // temp session.Store, mirroring the `config use-profile` pattern.
 var RunSessionsDelete = runSessionsDelete
 
-// DatabaseDeleteConfirm exposes the package-private helper that
-// builds the ConfirmAction for delete_database. Tests use it to pin
-// the "permanently delete" loudness adjustment (database is the only
-// slice using that emphatic verb).
-var DatabaseDeleteConfirm = databaseDeleteConfirm
+// DatabaseDeleteConfirm and MailAccountDeleteConfirm expose the
+// package-private helpers that build the delete ConfirmAction for their
+// slices. Tests use them to pin the "permanently delete" loudness
+// adjustment — the two data-loss deletes (a database drops all rows, a
+// mail account drops all stored messages) that use the emphatic verb
+// instead of the bare "delete" every other slice uses.
+var (
+	DatabaseDeleteConfirm    = databaseDeleteConfirm
+	MailAccountDeleteConfirm = mailAccountDeleteConfirm
+)