feat(admin): add email alias management commands

Add `zoh admin users aliases list|add|remove` for managing email aliases
via the Zoho Mail Admin API. Update README with alias docs and mermaid
architecture diagram.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: SeMmyT

README.md

@@ -11,7 +11,7 @@ zoh send --to team@company.com --subject "Deploy done" --body "v2.1 is live"
 ## Features
 
 - **Full Zoho Mail API** — folders, labels, messages, search, threads, attachments, send/reply/forward
-- **Full Zoho Admin API** — users, groups, domains, audit logs, login history, SMTP logs
+- **Full Zoho Admin API** — users, groups, domains, email alias management, audit logs, login history, SMTP logs
 - **Mail administration** — spam filters, retention policies, delivery logs
 - **8 data centers** — `us` `eu` `in` `au` `jp` `ca` `sa` `uk`
 - **Multiple output formats** — JSON (scriptable), plain (pipeable), rich (interactive tables)
@@ -20,6 +20,21 @@ zoh send --to team@company.com --subject "Deploy done" --body "v2.1 is live"
 - **Secure credential storage** — OS keyring or encrypted file (auto-detected for WSL/headless)
 - **Agent-friendly** — stable exit codes, `--results-only` JSON, `zoh schema` introspection
 
+## Architecture
+
+```mermaid
+graph LR
+    CLI[zoh CLI] --> SP[Service Provider]
+    SP --> AC[Admin Client]
+    SP --> MC[Mail Client]
+    AC --> API1[Zoho Mail Admin API]
+    MC --> API2[Zoho Mail API]
+    SP --> Auth[OAuth2 + Token Cache]
+    Auth --> KR[OS Keyring / Encrypted File]
+    API1 --> DC[8 Data Centers]
+    API2 --> DC
+```
+
 ## Install
 
 ```bash
@@ -78,6 +93,11 @@ zoh admin domains list
 zoh admin domains add example.com
 zoh admin domains verify example.com --method txt
 
+# Aliases
+zoh admin users aliases list user@example.com
+zoh admin users aliases add user@example.com alias1@example.com alias2@example.com
+zoh admin users aliases remove user@example.com old-alias@example.com --force
+
 # Audit
 zoh admin audit logs --from 2025-01-01 --to 2025-01-31
 zoh admin audit login-history --from 2025-01-01 --to 2025-01-31 --mode failedLoginActivity

internal/cli/admin_aliases.go

@@ -0,0 +1,146 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"github.com/SeMmyT/zohcli/internal/output"
+)
+
+// AdminAliasesListCmd lists aliases for a user
+type AdminAliasesListCmd struct {
+	Identifier string `arg:"" help:"User ID (zuid) or email address"`
+}
+
+// Run executes the list aliases command
+func (cmd *AdminAliasesListCmd) Run(sp *ServiceProvider, fp *FormatterProvider) error {
+	adminClient, err := sp.Admin()
+	if err != nil {
+		return err
+	}
+
+	ctx := context.Background()
+
+	_, user, err := resolveUserID(ctx, adminClient, cmd.Identifier)
+	if err != nil {
+		return &output.CLIError{
+			Message:  fmt.Sprintf("Failed to find user: %v", err),
+			ExitCode: output.ExitAPIError,
+		}
+	}
+
+	type AliasDisplay struct {
+		Email     string `json:"email"`
+		IsAlias   bool   `json:"isAlias"`
+		IsPrimary bool   `json:"isPrimary"`
+	}
+
+	var aliases []AliasDisplay
+	for _, ea := range user.EmailAddress {
+		aliases = append(aliases, AliasDisplay{
+			Email:     ea.MailID,
+			IsAlias:   ea.IsAlias,
+			IsPrimary: ea.IsPrimary,
+		})
+	}
+
+	columns := []output.Column{
+		{Name: "Email", Key: "Email"},
+		{Name: "Alias", Key: "IsAlias"},
+		{Name: "Primary", Key: "IsPrimary"},
+	}
+
+	return fp.Formatter.PrintList(aliases, columns)
+}
+
+// AdminAliasesAddCmd adds an alias to a user
+type AdminAliasesAddCmd struct {
+	Identifier string   `arg:"" help:"User ID (zuid) or email address"`
+	Aliases    []string `arg:"" help:"Email alias(es) to add"`
+}
+
+// Run executes the add alias command
+func (cmd *AdminAliasesAddCmd) Run(sp *ServiceProvider, fp *FormatterProvider, globals *Globals) error {
+	if globals.DryRun {
+		fmt.Fprintf(os.Stderr, "[DRY RUN] Would add aliases to %s: %v\n", cmd.Identifier, cmd.Aliases)
+		return nil
+	}
+
+	adminClient, err := sp.Admin()
+	if err != nil {
+		return err
+	}
+
+	ctx := context.Background()
+
+	_, user, err := resolveUserID(ctx, adminClient, cmd.Identifier)
+	if err != nil {
+		return &output.CLIError{
+			Message:  fmt.Sprintf("Failed to find user: %v", err),
+			ExitCode: output.ExitAPIError,
+		}
+	}
+
+	if err := adminClient.AddAlias(ctx, user.AccountID, cmd.Aliases); err != nil {
+		return &output.CLIError{
+			Message:  fmt.Sprintf("Failed to add aliases: %v", err),
+			ExitCode: output.ExitAPIError,
+		}
+	}
+
+	for _, alias := range cmd.Aliases {
+		fmt.Fprintf(os.Stderr, "Alias added: %s -> %s\n", alias, user.PrimaryEmail())
+	}
+
+	return nil
+}
+
+// AdminAliasesRemoveCmd removes an alias from a user
+type AdminAliasesRemoveCmd struct {
+	Identifier string   `arg:"" help:"User ID (zuid) or email address"`
+	Aliases    []string `arg:"" help:"Email alias(es) to remove"`
+}
+
+// Run executes the remove alias command
+func (cmd *AdminAliasesRemoveCmd) Run(sp *ServiceProvider, fp *FormatterProvider, globals *Globals) error {
+	if globals.DryRun {
+		fmt.Fprintf(os.Stderr, "[DRY RUN] Would remove aliases from %s: %v\n", cmd.Identifier, cmd.Aliases)
+		return nil
+	}
+
+	if !globals.Force {
+		return &output.CLIError{
+			Message:  "Removing aliases requires --force flag",
+			ExitCode: output.ExitUsage,
+		}
+	}
+
+	adminClient, err := sp.Admin()
+	if err != nil {
+		return err
+	}
+
+	ctx := context.Background()
+
+	_, user, err := resolveUserID(ctx, adminClient, cmd.Identifier)
+	if err != nil {
+		return &output.CLIError{
+			Message:  fmt.Sprintf("Failed to find user: %v", err),
+			ExitCode: output.ExitAPIError,
+		}
+	}
+
+	if err := adminClient.RemoveAlias(ctx, user.AccountID, cmd.Aliases); err != nil {
+		return &output.CLIError{
+			Message:  fmt.Sprintf("Failed to remove aliases: %v", err),
+			ExitCode: output.ExitAPIError,
+		}
+	}
+
+	for _, alias := range cmd.Aliases {
+		fmt.Fprintf(os.Stderr, "Alias removed: %s from %s\n", alias, user.PrimaryEmail())
+	}
+
+	return nil
+}

internal/cli/cli.go

@@ -119,6 +119,14 @@ type AdminUsersCmd struct {
 	Activate   AdminUsersActivateCmd   `cmd:"" help:"Activate a user account"`
 	Deactivate AdminUsersDeactivateCmd `cmd:"" help:"Deactivate a user account"`
 	Delete     AdminUsersDeleteCmd     `cmd:"" help:"Delete a user permanently"`
+	Aliases    AdminAliasesCmd         `cmd:"" help:"Manage user email aliases"`
+}
+
+// AdminAliasesCmd holds alias subcommands
+type AdminAliasesCmd struct {
+	List   AdminAliasesListCmd   `cmd:"" help:"List user email aliases"`
+	Add    AdminAliasesAddCmd    `cmd:"" help:"Add email alias(es) to a user"`
+	Remove AdminAliasesRemoveCmd `cmd:"" help:"Remove email alias(es) from a user"`
 }
 
 // AdminGroupsCmd holds group subcommands

internal/zoho/admin_client.go

@@ -576,6 +576,60 @@ func (ac *AdminClient) RemoveGroupMembers(ctx context.Context, zgid int64, membe
 	return nil
 }
 
+// AddAlias adds email aliases to a user account
+func (ac *AdminClient) AddAlias(ctx context.Context, accountID string, aliases []string) error {
+	path := fmt.Sprintf("/api/organization/%d/accounts/%s", ac.zoid, accountID)
+
+	req := AliasRequest{
+		Mode:       "addEmailAlias",
+		EmailAlias: aliases,
+	}
+
+	body, err := json.Marshal(req)
+	if err != nil {
+		return fmt.Errorf("marshal request: %w", err)
+	}
+
+	resp, err := ac.client.DoMail(ctx, http.MethodPut, path, bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return ac.parseErrorResponse(resp)
+	}
+
+	return nil
+}
+
+// RemoveAlias removes email aliases from a user account
+func (ac *AdminClient) RemoveAlias(ctx context.Context, accountID string, aliases []string) error {
+	path := fmt.Sprintf("/api/organization/%d/accounts/%s", ac.zoid, accountID)
+
+	req := AliasRequest{
+		Mode:       "removeEmailAlias",
+		EmailAlias: aliases,
+	}
+
+	body, err := json.Marshal(req)
+	if err != nil {
+		return fmt.Errorf("marshal request: %w", err)
+	}
+
+	resp, err := ac.client.DoMail(ctx, http.MethodPut, path, bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return ac.parseErrorResponse(resp)
+	}
+
+	return nil
+}
+
 // ListDomains fetches all domains in the organization
 func (ac *AdminClient) ListDomains(ctx context.Context) ([]Domain, error) {
 	path := fmt.Sprintf("/api/organization/%d/domains", ac.zoid)

internal/zoho/admin_service.go

@@ -37,6 +37,9 @@ type AdminService interface {
 	GetLoginHistory(ctx context.Context, mode string, startTime, endTime time.Time, batchSize int) ([]LoginHistoryEntry, error)
 	GetSMTPLogs(ctx context.Context, startTime, endTime time.Time, searchCriteria, searchKey string, limit int) ([]SMTPLogEntry, error)
 
+	AddAlias(ctx context.Context, accountID string, aliases []string) error
+	RemoveAlias(ctx context.Context, accountID string, aliases []string) error
+
 	GetAntispamOption(ctx context.Context, check string) (string, error)
 	SetAntispamOption(ctx context.Context, check, option string) error
 }

internal/zoho/types.go

@@ -332,6 +332,12 @@ type SMTPLogResponse struct {
 	} `json:"data"`
 }
 
+// AliasRequest is the request body for adding/removing email aliases
+type AliasRequest struct {
+	Mode       string   `json:"mode"`       // "addEmailAlias" or "removeEmailAlias"
+	EmailAlias []string `json:"emailAlias"`
+}
+
 // APIError represents an error response from the Zoho API
 type APIError struct {
 	Status struct {