mxgate 0.3.0__py3-none-any.whl

mxgate/__init__.py

@@ -0,0 +1,13 @@
+"""Python client for mxgate: email forwarding and send-as for a domain you own.
+
+    from mxgate import Mxgate, MxgateError
+
+    mx = Mxgate()  # the key comes from MXGATE_API_KEY
+    print(mx.account()["plan"])
+"""
+
+from ._version import __version__
+from .client import Mxgate, MxgateError
+from .webhooks import verify_webhook
+
+__all__ = ["Mxgate", "MxgateError", "__version__", "verify_webhook"]

mxgate/_operations.py

@@ -0,0 +1,45 @@
+"""Each `operationId` of the OpenAPI document and the `Mxgate` method that calls it.
+
+`tests/test_openapi.py` fails when the document has an operation that is not
+here, or when a method that is named here does not exist.
+"""
+
+from typing import Dict
+
+OPERATIONS: Dict[str, str] = {
+    "getIndex": "index",
+    "getStatus": "status",
+    "signUp": "signup",
+    "getAccount": "account",
+    "requestLogin": "login",
+    "confirmLogin": "confirm_login",
+    "startGoogleLogin": "google_login_url",
+    "confirmLoginGrant": "confirm_login_grant",
+    "logout": "logout",
+    "listKeys": "keys",
+    "recoverKey": "recover_key",
+    "confirmKeyRecovery": "confirm_recovery",
+    "rotateKey": "rotate_key",
+    "listConnectedApps": "apps",
+    "removeConnectedApp": "remove_app",
+    "createCheckout": "checkout",
+    "createPortalLink": "billing_portal",
+    "listDomains": "domains",
+    "addDomain": "add_domain",
+    "getDomain": "domain",
+    "deleteDomain": "remove_domain",
+    "verifyDomain": "verify_domain",
+    "listAliases": "aliases",
+    "setAlias": "set_alias",
+    "deleteAlias": "remove_alias",
+    "getSendAs": "send_as",
+    "createSmtpCredential": "create_smtp_credential",
+    "deleteSmtpCredential": "remove_smtp_credential",
+    "sendMessage": "send",
+    "listLogs": "logs",
+    "getNotifications": "notifications",
+    "setNotifications": "set_notifications",
+    "testWebhook": "test_webhook",
+    "listDestinations": "destinations",
+    "addDestination": "add_destination",
+}

mxgate/_version.py

@@ -0,0 +1,3 @@
+"""The version of the package. It is the version of the API that the client was written for."""
+
+__version__ = "0.3.0"

mxgate/client.py

@@ -0,0 +1,533 @@
+"""The client of the mxgate HTTP API. Standard library only.
+
+It mirrors the TypeScript client of the `mxgate` npm package: the same
+methods, the same places for the key, the same split of an alias address.
+"""
+
+import enum
+import json
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from http.client import HTTPException
+from typing import Any, Dict, Iterator, List, Mapping, Optional, Sequence, Tuple, Union
+
+from ._operations import OPERATIONS
+from ._version import __version__
+from .types import (
+    Account,
+    AddDomainResult,
+    AliasList,
+    BillingInterval,
+    Checkout,
+    ConnectedAppList,
+    Deleted,
+    DestinationList,
+    DestinationResult,
+    DomainList,
+    DomainResult,
+    Index,
+    KeyList,
+    LogDirection,
+    LogEntry,
+    LoginResult,
+    LogoutResult,
+    LogsPage,
+    LogStatus,
+    NewKey,
+    NotificationEvent,
+    NotificationSettings,
+    Portal,
+    RecoverResult,
+    RemovedApp,
+    SendAsResult,
+    SendResult,
+    Session,
+    SetAliasResult,
+    SignupResult,
+    SmtpCredentialCreated,
+    Status,
+    VerifyResult,
+    WebhookTestResult,
+)
+
+DEFAULT_API_URL = "https://api.mxgate.io"
+USER_AGENT = "mxgate-python/" + __version__
+CATCH_ALL = "*"
+
+__all__ = ["CATCH_ALL", "DEFAULT_API_URL", "OPERATIONS", "Mxgate", "MxgateError", "config_path", "split_alias_address"]
+
+
+class _NotGiven(enum.Enum):
+    """The default of a parameter where None has a meaning of its own."""
+
+    NOT_GIVEN = "NOT_GIVEN"
+
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN = _NotGiven.NOT_GIVEN
+
+
+class MxgateError(Exception):
+    """An error answer of the API (status 400 or more), or a failure before an answer came.
+
+    `code` is the `error` field of the body: let the program switch on it.
+    `message` is one sentence for a person. `fix` is the next step, when the
+    API gives one. A network failure has the status 0 and the code `network`.
+    """
+
+    status: int
+    code: str
+    message: str
+    fix: Optional[str]
+    retry_after_seconds: Optional[int]
+    upgrade_url: Optional[str]
+    body: Dict[str, Any]
+
+    def __init__(self, status: int, body: Optional[Mapping[str, Any]] = None) -> None:
+        self.status = status
+        self.body = dict(body) if isinstance(body, Mapping) else {}
+        code = self.body.get("error")
+        has_code = isinstance(code, str) and bool(code)
+        self.code = str(code) if has_code else "http_error"
+        message = self.body.get("message")
+        if isinstance(message, str) and message:
+            self.message = message
+        else:
+            self.message = self.code if has_code else "HTTP %d" % status
+        fix = self.body.get("fix")
+        self.fix = fix if isinstance(fix, str) and fix else None
+        retry = self.body.get("retry_after_seconds")
+        self.retry_after_seconds = int(retry) if isinstance(retry, (int, float)) and not isinstance(retry, bool) else None
+        upgrade = self.body.get("upgrade_url")
+        self.upgrade_url = upgrade if isinstance(upgrade, str) and upgrade else None
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        text = "%s: %s" % (self.code, self.message)
+        return "%s Fix: %s" % (text, self.fix) if self.fix else text
+
+    def __repr__(self) -> str:
+        return "MxgateError(status=%r, code=%r, message=%r)" % (self.status, self.code, self.message)
+
+
+# ---------------------------------------------------------------- names
+
+_DOMAIN_RE = re.compile(r"(?=.{1,253}\Z)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}")
+_LOCAL_RE = re.compile(r"[a-z0-9_+-]+(\.[a-z0-9_+-]+)*")
+
+
+def _parse_domain(value: str) -> str:
+    if not value.strip():
+        raise ValueError("give a domain name, for example example.com")
+    if "@" in value:
+        raise ValueError("give the domain only, without a mailbox part")
+    domain = value.strip().lower()
+    if domain.endswith("."):
+        domain = domain[:-1]
+    if not _DOMAIN_RE.fullmatch(domain):
+        raise ValueError('"%s" is not a domain name' % value)
+    return domain
+
+
+def _parse_alias_name(value: str) -> str:
+    name = value.strip().lower()
+    if not name:
+        raise ValueError('give the alias, for example "hello", or "*" for the catch-all')
+    if name == CATCH_ALL:
+        return CATCH_ALL
+    if "@" in name:
+        raise ValueError('give the part before the @ only, for example "hello"')
+    if len(name) > 64:
+        raise ValueError("an alias has at most 64 characters")
+    if not _LOCAL_RE.fullmatch(name):
+        raise ValueError('"%s" is not a valid alias: use letters, digits and . _ + -' % value)
+    return name
+
+
+def split_alias_address(address: str) -> Tuple[str, str]:
+    """Splits "hello@example.com", "*@example.com" or "@example.com" into (alias, domain).
+
+    The catch-all has the alias "*". Raises ValueError for a text that is not
+    an alias address.
+    """
+    text = address.strip()
+    at = text.rfind("@")
+    if at == -1:
+        raise ValueError('"%s" is not an alias address: write it as hello@example.com, or *@example.com for the catch-all' % address)
+    domain = _parse_domain(text[at + 1 :])
+    alias = _parse_alias_name(text[:at] or CATCH_ALL)
+    return alias, domain
+
+
+# ---------------------------------------------------------------- config
+
+
+def config_path(env: Optional[Mapping[str, str]] = None) -> str:
+    """The config file that `mxgate signup` of the CLI writes: ~/.config/mxgate/config.json."""
+    e = os.environ if env is None else env
+    base = e.get("XDG_CONFIG_HOME") or os.path.join(e.get("HOME") or os.path.expanduser("~"), ".config")
+    return os.path.join(base, "mxgate", "config.json")
+
+
+def _read_config_file(path: str) -> Dict[str, Any]:
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            parsed = json.load(f)
+    except (OSError, ValueError):
+        return {}  # no file yet, or not JSON
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _text(value: Any) -> Optional[str]:
+    return value if isinstance(value, str) and value else None
+
+
+def _segment(value: str) -> str:
+    # The same characters stay as in encodeURIComponent of the TypeScript client.
+    return urllib.parse.quote(value, safe="!*'()")
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """The API does not redirect. A redirect is not followed, so the key is not sent to a second host."""
+
+    def redirect_request(self, req: Any, fp: Any, code: Any, msg: Any, headers: Any, newurl: Any) -> None:
+        return None
+
+
+# ---------------------------------------------------------------- client
+
+
+class Mxgate:
+    """The client of the mxgate API.
+
+    The key: the `api_key` argument, then `MXGATE_API_KEY` in the environment,
+    then `api_key` in ~/.config/mxgate/config.json (`XDG_CONFIG_HOME` is
+    honoured). The base URL: the `api_url` argument, then `MXGATE_API_URL`,
+    then `api_url` in the config file, then https://api.mxgate.io.
+
+    Each method returns the parsed JSON answer as a `dict` and raises
+    `MxgateError` for an error answer or a network failure.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, api_url: Optional[str] = None, timeout: float = 30.0) -> None:
+        file: Dict[str, Any] = {}
+        if not (api_key and api_url):
+            file = _read_config_file(config_path())
+        self.api_key: Optional[str] = api_key or _text(os.environ.get("MXGATE_API_KEY")) or _text(file.get("api_key"))
+        url = api_url or _text(os.environ.get("MXGATE_API_URL")) or _text(file.get("api_url")) or DEFAULT_API_URL
+        if not re.match(r"https?://", url, re.IGNORECASE):
+            raise ValueError('api_url must start with https:// or http://, not "%s"' % url)
+        self.api_url: str = url.rstrip("/")
+        self.timeout: float = timeout
+        self._opener = urllib.request.build_opener(_NoRedirect())
+
+    def __repr__(self) -> str:
+        return "Mxgate(api_url=%r, api_key=%s)" % (self.api_url, "'***'" if self.api_key else "None")
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Mapping[str, Any]] = None,
+        query: Optional[Mapping[str, Any]] = None,
+        auth: bool = True,
+    ) -> Any:
+        """Sends one call and returns the parsed JSON answer. Raises MxgateError for a status of 400 or more."""
+        headers = {"Accept": "application/json", "User-Agent": USER_AGENT}
+        if auth:
+            if not self.api_key:
+                raise MxgateError(
+                    401,
+                    {
+                        "error": "no_api_key",
+                        "message": "No API key",
+                        "fix": 'Give api_key to Mxgate(), or set MXGATE_API_KEY. For a new account: Mxgate().signup("you@example.com").',
+                    },
+                )
+            headers["Authorization"] = "Bearer " + self.api_key
+        url = self.api_url + path
+        if query:
+            pairs = [(k, str(v)) for k, v in query.items() if v is not None and v != ""]
+            if pairs:
+                url += "?" + urllib.parse.urlencode(pairs)
+        data: Optional[bytes] = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        request = urllib.request.Request(url, data=data, method=method, headers=headers)
+        try:
+            with self._opener.open(request, timeout=self.timeout) as response:
+                status = int(response.status)
+                raw = response.read()
+        except urllib.error.HTTPError as err:
+            # An answer came, with an error status (or a redirect that was not followed).
+            status = int(err.code)
+            try:
+                raw = err.read()
+            except (OSError, HTTPException, AttributeError):
+                raw = b""
+            finally:
+                err.close()
+        except (urllib.error.URLError, OSError, HTTPException) as err:
+            reason = getattr(err, "reason", None) or err
+            raise MxgateError(
+                0,
+                {
+                    "error": "network",
+                    "message": "No answer from %s: %s" % (self.api_url, reason),
+                    "fix": "Make sure that the network and the API URL are correct, then try again.",
+                },
+            ) from err
+
+        if 300 <= status < 400:
+            raise MxgateError(status, {"error": "bad_response", "message": "HTTP %d: %s redirects" % (status, self.api_url), "fix": "Give the final URL as api_url."})
+        text = raw.decode("utf-8", errors="replace")
+        parsed: Any
+        try:
+            parsed = json.loads(text) if text.strip() else {}
+        except ValueError:
+            parsed = None
+        if not isinstance(parsed, dict):
+            # Not a JSON object: for example the page of a proxy.
+            raise MxgateError(status, {"error": "bad_response", "message": text[:200] or "HTTP %d" % status})
+        if status >= 400:
+            raise MxgateError(status, parsed)
+        return parsed
+
+    # ------------------------------------------------------------ account and keys
+
+    def index(self) -> Index:
+        """List the endpoints: the name and the version of the service, the setup steps, one line for each endpoint. No key."""
+        return self._request("GET", "/", auth=False)
+
+    def status(self) -> Status:
+        """Get the service status: the health of the service for the last 30 days, as an outside monitor saw it. No key."""
+        return self._request("GET", "/status", auth=False)
+
+    def signup(self, email: str) -> SignupResult:
+        """Create an account for an email address; the answer has its first API key, shown once. No key."""
+        return self._request("POST", "/v1/signup", {"email": email}, auth=False)
+
+    def account(self) -> Account:
+        """Get the account: the plan, the limits, the usage, the status and the state of the subscription."""
+        return self._request("GET", "/v1/account")
+
+    def login(self, email: str) -> LoginResult:
+        """Mail a six-digit sign-in code to the account address. For the website. No key."""
+        return self._request("POST", "/v1/login", {"email": email}, auth=False)
+
+    def confirm_login(self, email: str, code: str) -> Session:
+        """Get a session token for the sign-in code; it works like an API key for 30 days. No key."""
+        return self._request("POST", "/v1/login/confirm", {"email": email, "code": code}, auth=False)
+
+    def google_login_url(self, state: str) -> str:
+        """Sign in with Google: returns the URL that a browser opens. It makes no call; the endpoint answers 302 and is not for a program."""
+        return "%s/v1/login/google?%s" % (self.api_url, urllib.parse.urlencode({"state": state}))
+
+    def confirm_login_grant(self, grant: str) -> Session:
+        """Trade a Google grant for a session: gives a session token for the one-time grant of the sign-in with Google. No key."""
+        return self._request("POST", "/v1/login/grant", {"grant": grant}, auth=False)
+
+    def logout(self) -> LogoutResult:
+        """End the session: the session token of this client stops working. An API key has no sign-out."""
+        return self._request("POST", "/v1/logout")
+
+    def keys(self) -> KeyList:
+        """List the API keys of the account that work now; only the first 12 characters of each."""
+        return self._request("GET", "/v1/keys")
+
+    def recover_key(self, email: str) -> RecoverResult:
+        """Mail a key recovery token to the account address, for a lost API key. No key."""
+        return self._request("POST", "/v1/keys/recover", {"email": email}, auth=False)
+
+    def confirm_recovery(self, token: str) -> NewKey:
+        """Get a new key with the recovery token; every older key and session token stop working. No key."""
+        return self._request("POST", "/v1/keys/recover/confirm", {"token": token}, auth=False)
+
+    def rotate_key(self) -> NewKey:
+        """Replace the API key: the key of this client and every older key stop working. Store the new key."""
+        return self._request("POST", "/v1/keys/rotate")
+
+    def apps(self) -> ConnectedAppList:
+        """List connected apps: the apps that the owner allowed through OAuth, each with the date and the last use."""
+        return self._request("GET", "/v1/oauth/apps")
+
+    def remove_app(self, app_id: int) -> RemovedApp:
+        """Disconnect an app, by its `id` from `apps()`. Its token stops working at once."""
+        return self._request("DELETE", "/v1/oauth/apps/%s" % _segment(str(app_id)))
+
+    # ------------------------------------------------------------ billing
+
+    def checkout(self, interval: BillingInterval = "month") -> Checkout:
+        """Get a payment link for the paid plan (9 USD a month or 79 USD a year); a person opens it and pays."""
+        return self._request("POST", "/v1/billing/checkout", {"interval": interval})
+
+    def billing_portal(self) -> Portal:
+        """Get a subscription management link for a person: change the card, see invoices, or cancel."""
+        return self._request("POST", "/v1/billing/portal")
+
+    # ------------------------------------------------------------ domains
+
+    def domains(self) -> DomainList:
+        """List the domains of the account, each with its DNS records, its last check and its send-as state."""
+        return self._request("GET", "/v1/domains")
+
+    def add_domain(self, name: str) -> AddDomainResult:
+        """Add a domain to the account; the answer has the DNS records to publish."""
+        return self._request("POST", "/v1/domains", {"name": name})
+
+    def domain(self, name: str) -> DomainResult:
+        """Get one domain with the DNS records it needs, the result of its last check and its send-as state."""
+        return self._request("GET", "/v1/domains/%s" % _segment(name))
+
+    def verify_domain(self, name: str) -> VerifyResult:
+        """Check the DNS records of the domain now. Repeat the call until `verified` is true."""
+        return self._request("POST", "/v1/domains/%s/verify" % _segment(name))
+
+    def remove_domain(self, name: str) -> Deleted:
+        """Remove a domain, its aliases and its SMTP logins from the account."""
+        return self._request("DELETE", "/v1/domains/%s" % _segment(name))
+
+    # ------------------------------------------------------------ aliases and destinations
+
+    def aliases(self, domain: str) -> AliasList:
+        """List the aliases of the domain; each alias says if mail to it is forwarded now and, if not, why."""
+        return self._request("GET", "/v1/domains/%s/aliases" % _segment(domain))
+
+    def set_alias(self, address: str, to: Union[str, Sequence[str]]) -> SetAliasResult:
+        """Create or replace an alias. `address` is hello@example.com, or *@example.com for the catch-all; `to` is one mailbox or a list."""
+        alias, domain = split_alias_address(address)
+        destinations = [to] if isinstance(to, str) else list(to)
+        return self._request("PUT", "/v1/domains/%s/aliases/%s" % (_segment(domain), _segment(alias)), {"to": destinations})
+
+    def remove_alias(self, address: str) -> Deleted:
+        """Remove an alias, given as hello@example.com or *@example.com. The destinations stay in the account."""
+        alias, domain = split_alias_address(address)
+        return self._request("DELETE", "/v1/domains/%s/aliases/%s" % (_segment(domain), _segment(alias)))
+
+    def destinations(self) -> DestinationList:
+        """List the destinations: the mailboxes that the account can forward to, and if each one is confirmed."""
+        return self._request("GET", "/v1/destinations")
+
+    def add_destination(self, email: str) -> DestinationResult:
+        """Add a destination: a mailbox to forward to. A confirmation link is mailed to it."""
+        return self._request("POST", "/v1/destinations", {"email": email})
+
+    # ------------------------------------------------------------ send-as
+
+    def send_as(self, domain: str) -> SendAsResult:
+        """Get the send-as state of the domain: if it is ready and why not, the SMTP host, the ports and the SMTP logins."""
+        return self._request("GET", "/v1/domains/%s/smtp" % _segment(domain))
+
+    def create_smtp_credential(self, domain: str) -> SmtpCredentialCreated:
+        """Create an SMTP login for the domain; the password is shown once in the answer."""
+        return self._request("POST", "/v1/domains/%s/smtp" % _segment(domain))
+
+    def remove_smtp_credential(self, domain: str, username: str) -> Deleted:
+        """Remove an SMTP login of the domain; its password stops working at once."""
+        return self._request("DELETE", "/v1/domains/%s/smtp/%s" % (_segment(domain), _segment(username)))
+
+    def send(
+        self,
+        from_: str,
+        to: Union[str, Sequence[str]],
+        subject: str,
+        text: str,
+        *,
+        cc: Union[str, Sequence[str], None] = None,
+        bcc: Union[str, Sequence[str], None] = None,
+        reply_to: Optional[str] = None,
+        in_reply_to: Optional[str] = None,
+        references: Union[str, Sequence[str], None] = None,
+        copy_to_owner: bool = False,
+        idempotency_key: Optional[str] = None,
+    ) -> SendResult:
+        """Send one plain-text message from an address at a domain of the account. Give an `idempotency_key` so a retry cannot send a second copy."""
+
+        def many(value: Union[str, Sequence[str]]) -> Union[str, List[str]]:
+            return value if isinstance(value, str) else list(value)
+
+        body: Dict[str, Any] = {"from": from_, "to": many(to), "subject": subject, "text": text}
+        if cc is not None:
+            body["cc"] = many(cc)
+        if bcc is not None:
+            body["bcc"] = many(bcc)
+        if reply_to is not None:
+            body["reply_to"] = reply_to
+        if in_reply_to is not None:
+            body["in_reply_to"] = in_reply_to
+        if references is not None:
+            body["references"] = many(references)
+        if copy_to_owner:
+            body["copy_to_owner"] = True
+        if idempotency_key is not None:
+            body["idempotency_key"] = idempotency_key
+        return self._request("POST", "/v1/send", body)
+
+    # ------------------------------------------------------------ logs
+
+    def logs(
+        self,
+        *,
+        domain: Optional[str] = None,
+        direction: Optional[LogDirection] = None,
+        status: Optional[LogStatus] = None,
+        address: Optional[str] = None,
+        before: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> LogsPage:
+        """List the message log, newest first: one row for each message and recipient. `next_before` is `before` of the next page."""
+        query = {"domain": domain, "direction": direction, "status": status, "address": address, "before": before, "limit": limit}
+        return self._request("GET", "/v1/logs", query=query)
+
+    def iter_logs(
+        self,
+        *,
+        domain: Optional[str] = None,
+        direction: Optional[LogDirection] = None,
+        status: Optional[LogStatus] = None,
+        address: Optional[str] = None,
+        before: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[LogEntry]:
+        """Yields each row of the message log, newest first. It follows `next_before` to the end; `limit` is the size of one page."""
+        while True:
+            page = self.logs(domain=domain, direction=direction, status=status, address=address, before=before, limit=limit)
+            for entry in page.get("entries") or []:
+                yield entry
+            following = page.get("next_before")
+            if not following or following == before:
+                return
+            before = following
+
+    # ------------------------------------------------------------ notifications
+
+    def notifications(self) -> NotificationSettings:
+        """Get the notification settings and the 20 newest notifications."""
+        return self._request("GET", "/v1/notifications")
+
+    def set_notifications(
+        self,
+        *,
+        email: Optional[bool] = None,
+        events: Optional[Sequence[NotificationEvent]] = None,
+        webhook_url: Union[str, None, _NotGiven] = NOT_GIVEN,
+    ) -> NotificationSettings:
+        """Change the notification settings. A field that is not given stays as it is; `webhook_url=None` removes the webhook."""
+        body: Dict[str, Any] = {}
+        if email is not None:
+            body["email"] = email
+        if events is not None:
+            body["events"] = list(events)
+        if not isinstance(webhook_url, _NotGiven):
+            body["webhook_url"] = webhook_url
+        return self._request("PUT", "/v1/notifications", body)
+
+    def test_webhook(self) -> WebhookTestResult:
+        """Send a test webhook call now; the answer says what the webhook answered. Read `ok`."""
+        return self._request("POST", "/v1/notifications/test")