emailalias 1.0.0__py3-none-any.whl

emailalias/__init__.py

@@ -0,0 +1,11 @@
+from .client import Client
+from .errors import EmailAliasError, AuthenticationError, RateLimitError, NotFoundError
+
+__all__ = [
+    "Client",
+    "EmailAliasError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+]
+__version__ = "1.0.0"

emailalias/client.py

@@ -0,0 +1,176 @@
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .errors import (
+    AuthenticationError,
+    EmailAliasError,
+    NotFoundError,
+    RateLimitError,
+)
+
+DEFAULT_BASE_URL = "https://emailalias.io"
+
+
+class Client:
+    """Synchronous client for the EmailAlias REST API.
+
+    >>> from emailalias import Client
+    >>> client = Client(api_key="ea_live_xxx")
+    >>> client.list_aliases()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        session: Optional[requests.Session] = None,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+
+    # ── Low-level transport ──────────────────────────────────────────────
+    def _request(self, method: str, path: str, json: Any = None) -> Any:
+        url = f"{self.base_url}{path}"
+        res = self._session.request(
+            method,
+            url,
+            json=json,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Accept": "application/json",
+            },
+            timeout=self.timeout,
+        )
+
+        if res.status_code == 204:
+            return None
+
+        try:
+            body = res.json()
+        except ValueError:
+            body = {"detail": res.text}
+
+        if not res.ok:
+            detail = body.get("detail") if isinstance(body, dict) else None
+            message = detail if isinstance(detail, str) else str(body)
+            cls = {
+                401: AuthenticationError,
+                404: NotFoundError,
+                429: RateLimitError,
+            }.get(res.status_code, EmailAliasError)
+            raise cls(message, status=res.status_code)
+
+        return body
+
+    # ── Aliases ───────────────────────────────────────────────────────────
+    def list_aliases(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/api/aliases")
+
+    def create_alias(
+        self,
+        alias_type: str = "random",
+        label: Optional[str] = None,
+        domain: Optional[str] = None,
+        destination_email: Optional[str] = None,
+        custom_code: Optional[str] = None,
+        tag: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"alias_type": alias_type}
+        if label is not None:
+            body["label"] = label
+        if domain is not None:
+            body["domain"] = domain
+        if destination_email is not None:
+            body["destination_email"] = destination_email
+        if custom_code is not None:
+            body["custom_code"] = custom_code
+        if tag is not None:
+            body["tag"] = tag
+        return self._request("POST", "/api/aliases", json=body)
+
+    def update_alias(
+        self,
+        alias_id: str,
+        *,
+        active: Optional[bool] = None,
+        label: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {}
+        if active is not None:
+            body["active"] = active
+        if label is not None:
+            body["label"] = label
+        return self._request("PATCH", f"/api/aliases/{alias_id}", json=body)
+
+    def delete_alias(self, alias_id: str) -> None:
+        self._request("DELETE", f"/api/aliases/{alias_id}")
+
+    def list_available_domains(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/api/aliases/domains")
+
+    # ── Destinations ──────────────────────────────────────────────────────
+    def list_destinations(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/api/destinations")
+
+    def add_destination(self, email: str) -> Dict[str, Any]:
+        return self._request("POST", "/api/destinations", json={"email": email})
+
+    def resend_destination_verification(self, destination_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/api/destinations/{destination_id}/resend")
+
+    def delete_destination(self, destination_id: str) -> None:
+        self._request("DELETE", f"/api/destinations/{destination_id}")
+
+    # ── Send email ────────────────────────────────────────────────────────
+    def send_email(
+        self,
+        alias_id: str,
+        to_email: str,
+        subject: str,
+        body: str,
+        html_body: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {
+            "alias_id": alias_id,
+            "to_email": to_email,
+            "subject": subject,
+            "body": body,
+        }
+        if html_body is not None:
+            payload["html_body"] = html_body
+        return self._request("POST", "/api/send-email", json=payload)
+
+    # ── Custom Domains ────────────────────────────────────────────────────
+    def list_domains(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/api/domains")
+
+    def add_domain(self, domain_name: str) -> Dict[str, Any]:
+        return self._request("POST", "/api/domains", json={"domain_name": domain_name})
+
+    def verify_domain(self, domain_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/api/domains/{domain_id}/verify")
+
+    def delete_domain(self, domain_id: str) -> None:
+        self._request("DELETE", f"/api/domains/{domain_id}")
+
+    # ── Analytics ─────────────────────────────────────────────────────────
+    def get_dashboard_stats(self) -> Dict[str, Any]:
+        return self._request("GET", "/api/analytics/dashboard")
+
+    def list_logs(self, page: int = 1, per_page: int = 25) -> Dict[str, Any]:
+        return self._request(
+            "GET", f"/api/analytics/logs?page={page}&per_page={per_page}"
+        )
+
+    def list_exposure_events(
+        self, page: int = 1, per_page: int = 25
+    ) -> Dict[str, Any]:
+        return self._request(
+            "GET", f"/api/analytics/exposure?page={page}&per_page={per_page}"
+        )

emailalias/errors.py

@@ -0,0 +1,19 @@
+class EmailAliasError(Exception):
+    """Base exception. `status` is the HTTP code, `message` the server detail."""
+
+    def __init__(self, message: str, status: int = 0):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+class AuthenticationError(EmailAliasError):
+    """401 — invalid API key, or the key's owner is no longer Premium."""
+
+
+class NotFoundError(EmailAliasError):
+    """404."""
+
+
+class RateLimitError(EmailAliasError):
+    """429. Honour the `X-RateLimit-Reset` header before retrying."""

emailalias-1.0.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: emailalias
+Version: 1.0.0
+Summary: Official Python client for the EmailAlias API.
+Author: EmailAlias
+License: MIT License
+        
+        Copyright (c) 2026 EmailAlias.io
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://emailalias.io
+Project-URL: Documentation, https://emailalias.io/documentation
+Project-URL: Repository, https://github.com/emailalias/emailalias-python
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+# emailalias-python
+
+Official Python client for the [EmailAlias.io](https://emailalias.io) REST API.
+
+API access is a **Premium** feature. Generate a key from **Settings → API Keys** in the web dashboard.
+
+## Install
+
+```bash
+pip install emailalias
+```
+
+Or from source:
+
+```bash
+pip install git+https://github.com/emailalias/emailalias-python.git
+```
+
+## Quick start
+
+```python
+from emailalias import Client
+
+client = Client(api_key="ea_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
+
+# Create an alias
+alias = client.create_alias(alias_type="random", label="Shopping")
+print(alias["alias_email"])   # e.g. "x7k9m@email91.com"
+
+# List aliases
+for a in client.list_aliases():
+    print(a["alias_email"], "→", a["destination_email"])
+
+# Forward to a verified additional destination
+alias = client.create_alias(
+    alias_type="custom",
+    custom_code="work-signup",
+    label="Work",
+    destination_email="work@mycompany.com",  # must be verified on your account first
+)
+
+# Send email from an alias
+client.send_email(
+    alias_id=alias["id"],
+    to_email="recipient@example.com",
+    subject="Hello",
+    body="Sent from my alias.",
+)
+
+# Disable an alias
+client.update_alias(alias_id=alias["id"], active=False)
+```
+
+## Error handling
+
+```python
+from emailalias import Client, AuthenticationError, RateLimitError
+
+client = Client(api_key="ea_live_xxx")
+try:
+    client.list_aliases()
+except AuthenticationError:
+    # Invalid key, or account is no longer Premium
+    ...
+except RateLimitError:
+    # Respect X-RateLimit-Reset and retry
+    ...
+```
+
+## Configuration
+
+```python
+client = Client(
+    api_key="ea_live_xxx",
+    base_url="https://emailalias.io",  # override for staging/self-host
+    timeout=30.0,
+)
+```
+
+## Available methods
+
+| Method | Endpoint |
+|---|---|
+| `list_aliases()` | `GET /api/aliases` |
+| `create_alias(...)` | `POST /api/aliases` |
+| `update_alias(id, active=, label=)` | `PATCH /api/aliases/{id}` |
+| `delete_alias(id)` | `DELETE /api/aliases/{id}` |
+| `list_available_domains()` | `GET /api/aliases/domains` |
+| `list_destinations()` | `GET /api/destinations` |
+| `add_destination(email)` | `POST /api/destinations` |
+| `resend_destination_verification(id)` | `POST /api/destinations/{id}/resend` |
+| `delete_destination(id)` | `DELETE /api/destinations/{id}` |
+| `send_email(alias_id, to_email, subject, body, html_body=)` | `POST /api/send-email` |
+| `list_domains()` | `GET /api/domains` |
+| `add_domain(name)` | `POST /api/domains` |
+| `verify_domain(id)` | `POST /api/domains/{id}/verify` |
+| `delete_domain(id)` | `DELETE /api/domains/{id}` |
+| `get_dashboard_stats()` | `GET /api/analytics/dashboard` |
+| `list_logs(page=, per_page=)` | `GET /api/analytics/logs` |
+| `list_exposure_events(page=, per_page=)` | `GET /api/analytics/exposure` |
+
+Full API reference: <https://emailalias.io/documentation>
+
+## License
+
+MIT

emailalias-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+emailalias/__init__.py,sha256=Xjie9tvVf7k8oFcdSrvOhCv9a7dvMW9iLxSs2jf8_2o,259
+emailalias/client.py,sha256=pfn3l28XOOydDjvSzk2twBfecfozvjn-vuFuyHR-7a8,6629
+emailalias/errors.py,sha256=1l7Degm5nfgDkoTtRGuEHVz7yoVAItkERWguK6YZn1Y,554
+emailalias-1.0.0.dist-info/licenses/LICENSE,sha256=VmZ1ukK2Gq9jDEVa893cqcDR69UK9KQECY0WGNUHyTo,1070
+emailalias-1.0.0.dist-info/METADATA,sha256=IJndlEF1BTP4lxd6e_JcGI5ce3tRXdrXFEcDpFfRn5E,4696
+emailalias-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+emailalias-1.0.0.dist-info/top_level.txt,sha256=ux14GRquM3pbi4hc6Sf8NOCmksJEBgP28OOUwbaQktc,11
+emailalias-1.0.0.dist-info/RECORD,,

emailalias-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

emailalias-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EmailAlias.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

emailalias-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+emailalias