"""``mail.*`` — mail domains, mailboxes, forwarders.

Note: the ISPConfig remote method is ``mail_forward_*`` (singular), not
``mail_forwarding_*``. Our wrapper exposes :meth:`MailModule.forward_add`
etc; the old ``forwarding`` names are available as aliases for anyone coming
from the PHP snippets.
"""

from __future__ import annotations

import logging
from collections.abc import Mapping
from typing import TYPE_CHECKING, Any, cast

from .types import MailDomain, MailUser

if TYPE_CHECKING:
    from .client import ISPConfigClient

log = logging.getLogger("ispconfig.mail")


class MailModule:
    def __init__(self, client: ISPConfigClient) -> None:
        self._c = client

    # ---- AUTO-GENERATED START (do not hand-edit above this line) ----
    # Regenerate with: python3 tools/gen_methods.py

    def mail_alias_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_alias_add``.

        Source: ``mail.inc.php`` line 424.
        PHP signature: ``mail_alias_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_alias_add", ("client_id", client_id), ("params", params))

    def mail_alias_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_alias_delete``.

        Source: ``mail.inc.php`` line 466.
        PHP signature: ``mail_alias_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_alias_delete", ("primary_id", primary_id))

    def mail_alias_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_alias_get``.

        Source: ``mail.inc.php`` line 410.
        PHP signature: ``mail_alias_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_alias_get", ("primary_id", primary_id))

    def mail_alias_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_alias_update``.

        Source: ``mail.inc.php`` line 444.
        PHP signature: ``mail_alias_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_alias_update", ("client_id", client_id), ("primary_id", primary_id), ("params", params)
        )

    def mail_aliasdomain_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_aliasdomain_add``.

        Source: ``mail.inc.php`` line 111.
        PHP signature: ``mail_aliasdomain_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_aliasdomain_add", ("client_id", client_id), ("params", params))

    def mail_aliasdomain_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_aliasdomain_delete``.

        Source: ``mail.inc.php`` line 133.
        PHP signature: ``mail_aliasdomain_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_aliasdomain_delete", ("primary_id", primary_id))

    def mail_aliasdomain_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_aliasdomain_get``.

        Source: ``mail.inc.php`` line 97.
        PHP signature: ``mail_aliasdomain_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_aliasdomain_get", ("primary_id", primary_id))

    def mail_aliasdomain_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_aliasdomain_update``.

        Source: ``mail.inc.php`` line 121.
        PHP signature: ``mail_aliasdomain_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_aliasdomain_update",
            ("client_id", client_id),
            ("primary_id", primary_id),
            ("params", params),
        )

    def mail_blacklist_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_blacklist_add``.

        Source: ``mail.inc.php`` line 1040.
        PHP signature: ``mail_blacklist_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_blacklist_add", ("client_id", client_id), ("params", params))

    def mail_blacklist_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_blacklist_delete``.

        Source: ``mail.inc.php`` line 1062.
        PHP signature: ``mail_blacklist_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_blacklist_delete", ("primary_id", primary_id))

    def mail_blacklist_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_blacklist_get``.

        Source: ``mail.inc.php`` line 1026.
        PHP signature: ``mail_blacklist_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_blacklist_get", ("primary_id", primary_id))

    def mail_blacklist_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_blacklist_update``.

        Source: ``mail.inc.php`` line 1050.
        PHP signature: ``mail_blacklist_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_blacklist_update", ("client_id", client_id), ("primary_id", primary_id), ("params", params)
        )

    def mail_catchall_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_catchall_add``.

        Source: ``mail.inc.php`` line 543.
        PHP signature: ``mail_catchall_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_catchall_add", ("client_id", client_id), ("params", params))

    def mail_catchall_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_catchall_delete``.

        Source: ``mail.inc.php`` line 564.
        PHP signature: ``mail_catchall_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_catchall_delete", ("primary_id", primary_id))

    def mail_catchall_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_catchall_get``.

        Source: ``mail.inc.php`` line 529.
        PHP signature: ``mail_catchall_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_catchall_get", ("primary_id", primary_id))

    def mail_catchall_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_catchall_update``.

        Source: ``mail.inc.php`` line 553.
        PHP signature: ``mail_catchall_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_catchall_update", ("client_id", client_id), ("primary_id", primary_id), ("params", params)
        )

    def mail_domain_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_domain_add``.

        Source: ``mail.inc.php`` line 57.
        PHP signature: ``mail_domain_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_domain_add", ("client_id", client_id), ("params", params))

    def mail_domain_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_domain_delete``.

        Source: ``mail.inc.php`` line 86.
        PHP signature: ``mail_domain_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_domain_delete", ("primary_id", primary_id))

    def mail_domain_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_domain_get``.

        Source: ``mail.inc.php`` line 43.
        PHP signature: ``mail_domain_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_domain_get", ("primary_id", primary_id))

    def mail_domain_get_by_domain(self, domain: Any) -> Any:
        """
        Fetch the mail_domain record for the provided domain.

        Source: ``mail.inc.php`` line 1132.
        PHP signature: ``mail_domain_get_by_domain($session_id, $domain)``.

        Params (from PHPDoc):
            the (string): fully qualified domain (or subdomain)

        Returns: array - array of arrays corresponding to the mail_domain table's records

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_domain_get_by_domain", ("domain", domain))

    def mail_domain_set_status(self, primary_id: Any, status: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_domain_set_status``.

        Source: ``mail.inc.php`` line 1147.
        PHP signature: ``mail_domain_set_status($session_id, $primary_id, $status)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_domain_set_status", ("primary_id", primary_id), ("status", status))

    def mail_domain_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_domain_update``.

        Source: ``mail.inc.php`` line 75.
        PHP signature: ``mail_domain_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_domain_update", ("client_id", client_id), ("primary_id", primary_id), ("params", params)
        )

    def mail_fetchmail_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_fetchmail_add``.

        Source: ``mail.inc.php`` line 940.
        PHP signature: ``mail_fetchmail_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_fetchmail_add", ("client_id", client_id), ("params", params))

    def mail_fetchmail_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_fetchmail_delete``.

        Source: ``mail.inc.php`` line 962.
        PHP signature: ``mail_fetchmail_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_fetchmail_delete", ("primary_id", primary_id))

    def mail_fetchmail_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_fetchmail_get``.

        Source: ``mail.inc.php`` line 926.
        PHP signature: ``mail_fetchmail_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_fetchmail_get", ("primary_id", primary_id))

    def mail_fetchmail_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_fetchmail_update``.

        Source: ``mail.inc.php`` line 950.
        PHP signature: ``mail_fetchmail_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_fetchmail_update", ("client_id", client_id), ("primary_id", primary_id), ("params", params)
        )

    def mail_filter_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_filter_add``.

        Source: ``mail.inc.php`` line 1090.
        PHP signature: ``mail_filter_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_filter_add", ("client_id", client_id), ("params", params))

    def mail_filter_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_filter_delete``.

        Source: ``mail.inc.php`` line 1112.
        PHP signature: ``mail_filter_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_filter_delete", ("primary_id", primary_id))

    def mail_filter_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_filter_get``.

        Source: ``mail.inc.php`` line 1076.
        PHP signature: ``mail_filter_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_filter_get", ("primary_id", primary_id))

    def mail_filter_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_filter_update``.

        Source: ``mail.inc.php`` line 1100.
        PHP signature: ``mail_filter_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_filter_update", ("client_id", client_id), ("primary_id", primary_id), ("params", params)
        )

    def mail_forward_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_forward_add``.

        Source: ``mail.inc.php`` line 493.
        PHP signature: ``mail_forward_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_forward_add", ("client_id", client_id), ("params", params))

    def mail_forward_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_forward_delete``.

        Source: ``mail.inc.php`` line 515.
        PHP signature: ``mail_forward_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_forward_delete", ("primary_id", primary_id))

    def mail_forward_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_forward_get``.

        Source: ``mail.inc.php`` line 479.
        PHP signature: ``mail_forward_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_forward_get", ("primary_id", primary_id))

    def mail_forward_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_forward_update``.

        Source: ``mail.inc.php`` line 503.
        PHP signature: ``mail_forward_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_forward_update", ("client_id", client_id), ("primary_id", primary_id), ("params", params)
        )

    def mail_mailinglist_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_mailinglist_add``.

        Source: ``mail.inc.php`` line 160.
        PHP signature: ``mail_mailinglist_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_mailinglist_add", ("client_id", client_id), ("params", params))

    def mail_mailinglist_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_mailinglist_delete``.

        Source: ``mail.inc.php`` line 182.
        PHP signature: ``mail_mailinglist_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_mailinglist_delete", ("primary_id", primary_id))

    def mail_mailinglist_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_mailinglist_get``.

        Source: ``mail.inc.php`` line 146.
        PHP signature: ``mail_mailinglist_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_mailinglist_get", ("primary_id", primary_id))

    def mail_mailinglist_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_mailinglist_update``.

        Source: ``mail.inc.php`` line 171.
        PHP signature: ``mail_mailinglist_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_mailinglist_update",
            ("client_id", client_id),
            ("primary_id", primary_id),
            ("params", params),
        )

    def mail_policy_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_policy_add``.

        Source: ``mail.inc.php`` line 890.
        PHP signature: ``mail_policy_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_policy_add", ("client_id", client_id), ("params", params))

    def mail_policy_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_policy_delete``.

        Source: ``mail.inc.php`` line 912.
        PHP signature: ``mail_policy_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_policy_delete", ("primary_id", primary_id))

    def mail_policy_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_policy_get``.

        Source: ``mail.inc.php`` line 876.
        PHP signature: ``mail_policy_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_policy_get", ("primary_id", primary_id))

    def mail_policy_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_policy_update``.

        Source: ``mail.inc.php`` line 900.
        PHP signature: ``mail_policy_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_policy_update", ("client_id", client_id), ("primary_id", primary_id), ("params", params)
        )

    def mail_relay_domain_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_relay_domain_add``.

        Source: ``mail.inc.php`` line 678.
        PHP signature: ``mail_relay_domain_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_relay_domain_add", ("client_id", client_id), ("params", params))

    def mail_relay_domain_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_relay_domain_delete``.

        Source: ``mail.inc.php`` line 688.
        PHP signature: ``mail_relay_domain_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_relay_domain_delete", ("primary_id", primary_id))

    def mail_relay_domain_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_relay_domain_get``.

        Source: ``mail.inc.php`` line 699.
        PHP signature: ``mail_relay_domain_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_relay_domain_get", ("primary_id", primary_id))

    def mail_relay_domain_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_relay_domain_update``.

        Source: ``mail.inc.php`` line 713.
        PHP signature: ``mail_relay_domain_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_relay_domain_update",
            ("client_id", client_id),
            ("primary_id", primary_id),
            ("params", params),
        )

    def mail_relay_recipient_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_relay_recipient_add``.

        Source: ``mail.inc.php`` line 642.
        PHP signature: ``mail_relay_recipient_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_relay_recipient_add", ("client_id", client_id), ("params", params))

    def mail_relay_recipient_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_relay_recipient_delete``.

        Source: ``mail.inc.php`` line 664.
        PHP signature: ``mail_relay_recipient_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_relay_recipient_delete", ("primary_id", primary_id))

    def mail_relay_recipient_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_relay_recipient_get``.

        Source: ``mail.inc.php`` line 627.
        PHP signature: ``mail_relay_recipient_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_relay_recipient_get", ("primary_id", primary_id))

    def mail_relay_recipient_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_relay_recipient_update``.

        Source: ``mail.inc.php`` line 652.
        PHP signature: ``mail_relay_recipient_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_relay_recipient_update",
            ("client_id", client_id),
            ("primary_id", primary_id),
            ("params", params),
        )

    def mail_spamfilter_blacklist_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_blacklist_add``.

        Source: ``mail.inc.php`` line 790.
        PHP signature: ``mail_spamfilter_blacklist_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_spamfilter_blacklist_add", ("client_id", client_id), ("params", params))

    def mail_spamfilter_blacklist_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_blacklist_delete``.

        Source: ``mail.inc.php`` line 812.
        PHP signature: ``mail_spamfilter_blacklist_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_spamfilter_blacklist_delete", ("primary_id", primary_id))

    def mail_spamfilter_blacklist_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_blacklist_get``.

        Source: ``mail.inc.php`` line 776.
        PHP signature: ``mail_spamfilter_blacklist_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_spamfilter_blacklist_get", ("primary_id", primary_id))

    def mail_spamfilter_blacklist_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_blacklist_update``.

        Source: ``mail.inc.php`` line 800.
        PHP signature: ``mail_spamfilter_blacklist_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_spamfilter_blacklist_update",
            ("client_id", client_id),
            ("primary_id", primary_id),
            ("params", params),
        )

    def mail_spamfilter_user_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_user_add``.

        Source: ``mail.inc.php`` line 840.
        PHP signature: ``mail_spamfilter_user_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_spamfilter_user_add", ("client_id", client_id), ("params", params))

    def mail_spamfilter_user_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_user_delete``.

        Source: ``mail.inc.php`` line 862.
        PHP signature: ``mail_spamfilter_user_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_spamfilter_user_delete", ("primary_id", primary_id))

    def mail_spamfilter_user_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_user_get``.

        Source: ``mail.inc.php`` line 826.
        PHP signature: ``mail_spamfilter_user_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_spamfilter_user_get", ("primary_id", primary_id))

    def mail_spamfilter_user_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_user_update``.

        Source: ``mail.inc.php`` line 850.
        PHP signature: ``mail_spamfilter_user_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_spamfilter_user_update",
            ("client_id", client_id),
            ("primary_id", primary_id),
            ("params", params),
        )

    def mail_spamfilter_whitelist_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_whitelist_add``.

        Source: ``mail.inc.php`` line 740.
        PHP signature: ``mail_spamfilter_whitelist_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_spamfilter_whitelist_add", ("client_id", client_id), ("params", params))

    def mail_spamfilter_whitelist_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_whitelist_delete``.

        Source: ``mail.inc.php`` line 762.
        PHP signature: ``mail_spamfilter_whitelist_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_spamfilter_whitelist_delete", ("primary_id", primary_id))

    def mail_spamfilter_whitelist_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_whitelist_get``.

        Source: ``mail.inc.php`` line 726.
        PHP signature: ``mail_spamfilter_whitelist_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_spamfilter_whitelist_get", ("primary_id", primary_id))

    def mail_spamfilter_whitelist_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_spamfilter_whitelist_update``.

        Source: ``mail.inc.php`` line 750.
        PHP signature: ``mail_spamfilter_whitelist_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_spamfilter_whitelist_update",
            ("client_id", client_id),
            ("primary_id", primary_id),
            ("params", params),
        )

    def mail_transport_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_transport_add``.

        Source: ``mail.inc.php`` line 591.
        PHP signature: ``mail_transport_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_transport_add", ("client_id", client_id), ("params", params))

    def mail_transport_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_transport_delete``.

        Source: ``mail.inc.php`` line 613.
        PHP signature: ``mail_transport_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_transport_delete", ("primary_id", primary_id))

    def mail_transport_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_transport_get``.

        Source: ``mail.inc.php`` line 577.
        PHP signature: ``mail_transport_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_transport_get", ("primary_id", primary_id))

    def mail_transport_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_transport_update``.

        Source: ``mail.inc.php`` line 601.
        PHP signature: ``mail_transport_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_transport_update", ("client_id", client_id), ("primary_id", primary_id), ("params", params)
        )

    def mail_user_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_user_add``.

        Source: ``mail.inc.php`` line 226.
        PHP signature: ``mail_user_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_user_add", ("client_id", client_id), ("params", params))

    def mail_user_backup(self, primary_id: Any, action_type: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_user_backup``.

        Source: ``mail.inc.php`` line 366.
        PHP signature: ``mail_user_backup($session_id, $primary_id, $action_type)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_user_backup", ("primary_id", primary_id), ("action_type", action_type))

    def mail_user_backup_list(self, primary_id: Any = None) -> Any:
        """
        Auto-generated wrapper for ``mail_user_backup_list``.

        Source: ``mail.inc.php`` line 343.
        PHP signature: ``mail_user_backup_list($session_id, $primary_id = null)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_user_backup_list", ("primary_id", primary_id))

    def mail_user_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_user_delete``.

        Source: ``mail.inc.php`` line 279.
        PHP signature: ``mail_user_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_user_delete", ("primary_id", primary_id))

    def mail_user_filter_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_user_filter_add``.

        Source: ``mail.inc.php`` line 303.
        PHP signature: ``mail_user_filter_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_user_filter_add", ("client_id", client_id), ("params", params))

    def mail_user_filter_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_user_filter_delete``.

        Source: ``mail.inc.php`` line 328.
        PHP signature: ``mail_user_filter_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_user_filter_delete", ("primary_id", primary_id))

    def mail_user_filter_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_user_filter_get``.

        Source: ``mail.inc.php`` line 291.
        PHP signature: ``mail_user_filter_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_user_filter_get", ("primary_id", primary_id))

    def mail_user_filter_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_user_filter_update``.

        Source: ``mail.inc.php`` line 315.
        PHP signature: ``mail_user_filter_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_user_filter_update",
            ("client_id", client_id),
            ("primary_id", primary_id),
            ("params", params),
        )

    def mail_user_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_user_get``.

        Source: ``mail.inc.php`` line 193.
        PHP signature: ``mail_user_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_user_get", ("primary_id", primary_id))

    def mail_user_get_all_by_client(self, client_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_user_get_all_by_client``.

        Source: ``mail.inc.php`` line 207.
        PHP signature: ``mail_user_get_all_by_client($session_id, $client_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_user_get_all_by_client", ("client_id", client_id))

    def mail_user_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_user_update``.

        Source: ``mail.inc.php`` line 255.
        PHP signature: ``mail_user_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_user_update", ("client_id", client_id), ("primary_id", primary_id), ("params", params)
        )

    def mail_whitelist_add(self, client_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_whitelist_add``.

        Source: ``mail.inc.php`` line 990.
        PHP signature: ``mail_whitelist_add($session_id, $client_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_whitelist_add", ("client_id", client_id), ("params", params))

    def mail_whitelist_delete(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_whitelist_delete``.

        Source: ``mail.inc.php`` line 1012.
        PHP signature: ``mail_whitelist_delete($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_whitelist_delete", ("primary_id", primary_id))

    def mail_whitelist_get(self, primary_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_whitelist_get``.

        Source: ``mail.inc.php`` line 976.
        PHP signature: ``mail_whitelist_get($session_id, $primary_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mail_whitelist_get", ("primary_id", primary_id))

    def mail_whitelist_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
        """
        Auto-generated wrapper for ``mail_whitelist_update``.

        Source: ``mail.inc.php`` line 1000.
        PHP signature: ``mail_whitelist_update($session_id, $client_id, $primary_id, $params)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call(
            "mail_whitelist_update", ("client_id", client_id), ("primary_id", primary_id), ("params", params)
        )

    def mailquota_get_by_user(self, client_id: Any) -> Any:
        """
        Auto-generated wrapper for ``mailquota_get_by_user``.

        Source: ``mail.inc.php`` line 1171.
        PHP signature: ``mailquota_get_by_user($session_id, $client_id)``.

        AUTO-GENERATED - param shapes may need verification against your
        ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
        """
        return self._c._call("mailquota_get_by_user", ("client_id", client_id))

    # ---- AUTO-GENERATED END ----

    # ---- HAND-EDIT ONLY BELOW ----

    # ---- HAND-EDIT ONLY BELOW ----

    # ---- HAND-EDIT ONLY BELOW ----

    # ---- mail domains -------------------------------------------------

    def domain_get(self, primary_id: int) -> MailDomain:
        return cast(MailDomain, self._c._call("mail_domain_get", ("primary_id", int(primary_id))))

    def domain_get_by_domain(self, domain: str) -> list[MailDomain]:
        return self._c._call("mail_domain_get_by_domain", ("domain", domain)) or []

    def domain_add(self, client_id: int, params: Mapping[str, Any]) -> int:
        return int(
            self._c._call(
                "mail_domain_add",
                ("client_id", int(client_id)),
                ("params", dict(params)),
            )
        )

    def domain_update(self, client_id: int, primary_id: int, params: Mapping[str, Any]) -> int:
        return int(
            self._c._call(
                "mail_domain_update",
                ("client_id", int(client_id)),
                ("primary_id", int(primary_id)),
                ("params", dict(params)),
            )
        )

    def domain_delete(self, primary_id: int) -> int:
        return int(self._c._call("mail_domain_delete", ("primary_id", int(primary_id))))

    # ---- mail users ---------------------------------------------------

    def user_get(self, primary_id: int | Mapping[str, Any]) -> MailUser | list[MailUser]:
        """Fetch a mailuser.

        Pass an int ``mailuser_id`` to get a single row, or a dict of filter
        key/values (e.g. ``{'email': 'x@y.com'}``) to get a list.

        .. note::
           ISPConfig's SOAP is inconsistent: a filter dict that matches
           multiple rows returns an array, but a filter dict that matches
           *exactly one* row sometimes returns a single map instead of a
           1-element array. When a filter dict is passed we always normalize
           to a list so callers can iterate without surprises.
        """
        if isinstance(primary_id, Mapping):
            result = self._c._call("mail_user_get", ("primary_id", dict(primary_id)))
            if result is None:
                return cast(list[MailUser], [])
            if isinstance(result, list):
                return cast(list[MailUser], result)
            # single-hit quirk — wrap into a list for consistency.
            return cast(list[MailUser], [result])
        return cast(MailUser, self._c._call("mail_user_get", ("primary_id", int(primary_id))))

    def user_add(self, client_id: int, params: Mapping[str, Any]) -> int:
        return int(
            self._c._call(
                "mail_user_add",
                ("client_id", int(client_id)),
                ("params", dict(params)),
            )
        )

    def user_update(self, client_id: int, primary_id: int, params: Mapping[str, Any]) -> int:
        return int(
            self._c._call(
                "mail_user_update",
                ("client_id", int(client_id)),
                ("primary_id", int(primary_id)),
                ("params", dict(params)),
            )
        )

    def user_delete(self, primary_id: int) -> int:
        return int(self._c._call("mail_user_delete", ("primary_id", int(primary_id))))

    # ---- mail forward -------------------------------------------------

    def forward_add(self, client_id: int, params: Mapping[str, Any]) -> int:
        return int(
            self._c._call(
                "mail_forward_add",
                ("client_id", int(client_id)),
                ("params", dict(params)),
            )
        )

    def forward_update(self, client_id: int, primary_id: int, params: Mapping[str, Any]) -> int:
        return int(
            self._c._call(
                "mail_forward_update",
                ("client_id", int(client_id)),
                ("primary_id", int(primary_id)),
                ("params", dict(params)),
            )
        )

    def forward_delete(self, primary_id: int) -> int:
        return int(self._c._call("mail_forward_delete", ("primary_id", int(primary_id))))

    # Aliases for callers coming from the old ``mail_forwarding_*`` PHP names.
    forwarding_add = forward_add
    forwarding_update = forward_update
    forwarding_delete = forward_delete

    # ---- helpers ------------------------------------------------------

    def create_mailbox(
        self,
        client_id: int,
        domain: str,
        local_part: str,
        password: str,
        *,
        server_id: int = 1,
        quota_mb: int = 1024,
        name: str | None = None,
    ) -> int:
        """Shorthand for ``user_add`` with typical defaults.

        Returns the new ``mailuser_id``.
        """
        email = f"{local_part}@{domain}"
        params: dict[str, Any] = {
            "server_id": int(server_id),
            "email": email,
            "login": email,
            "password": password,
            "name": name or local_part,
            "quota": int(quota_mb) * 1024 * 1024,  # ISPConfig stores bytes
            "postfix": "y",
            "access": "y",
            "disableimap": "n",
            "disablepop3": "n",
            "disablesmtp": "n",
        }
        return self.user_add(client_id, params)