mailglyph 2.0.0__py3-none-any.whl

mailglyph/__init__.py

@@ -0,0 +1,47 @@
+from .client import AsyncMailGlyph, MailGlyph
+from .exceptions import (
+    ApiError,
+    AuthenticationError,
+    MailGlyphError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from .models import (
+    Campaign,
+    Contact,
+    FilterCondition,
+    FilterGroup,
+    Segment,
+    SegmentFilter,
+    SendEmailResult,
+    StaticSegmentMembersAddResult,
+    StaticSegmentMembersRemoveResult,
+    TrackEventResult,
+    VerifyEmailResult,
+)
+
+__version__ = "2.0.0"
+
+__all__ = [
+    "ApiError",
+    "AsyncMailGlyph",
+    "AuthenticationError",
+    "Campaign",
+    "Contact",
+    "FilterCondition",
+    "FilterGroup",
+    "MailGlyph",
+    "MailGlyphError",
+    "NotFoundError",
+    "RateLimitError",
+    "Segment",
+    "SegmentFilter",
+    "SendEmailResult",
+    "StaticSegmentMembersAddResult",
+    "StaticSegmentMembersRemoveResult",
+    "TrackEventResult",
+    "ValidationError",
+    "VerifyEmailResult",
+    "__version__",
+]

mailglyph/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

mailglyph/client.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from .http_client import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, HttpClient
+from .resources import (
+    AsyncCampaignsResource,
+    AsyncContactsResource,
+    AsyncEmailsResource,
+    AsyncEventsResource,
+    AsyncSegmentsResource,
+    CampaignsResource,
+    ContactsResource,
+    EmailsResource,
+    EventsResource,
+    SegmentsResource,
+)
+
+
+class MailGlyph:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._http_client = HttpClient(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self.emails = EmailsResource(self._http_client)
+        self.events = EventsResource(self._http_client)
+        self.contacts = ContactsResource(self._http_client)
+        self.campaigns = CampaignsResource(self._http_client)
+        self.segments = SegmentsResource(self._http_client)
+
+    def close(self) -> None:
+        self._http_client.close()
+
+    def __enter__(self) -> MailGlyph:
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, exc_tb: object) -> None:
+        self.close()
+
+
+class AsyncMailGlyph:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._http_client = HttpClient(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self.emails = AsyncEmailsResource(self._http_client)
+        self.events = AsyncEventsResource(self._http_client)
+        self.contacts = AsyncContactsResource(self._http_client)
+        self.campaigns = AsyncCampaignsResource(self._http_client)
+        self.segments = AsyncSegmentsResource(self._http_client)
+
+    async def close(self) -> None:
+        await self._http_client.aclose()
+
+    async def __aenter__(self) -> AsyncMailGlyph:
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, exc_tb: object) -> None:
+        await self.close()

mailglyph/exceptions.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class MailGlyphError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        payload: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.payload = payload
+
+
+class AuthenticationError(MailGlyphError):
+    pass
+
+
+class ValidationError(MailGlyphError):
+    pass
+
+
+class NotFoundError(MailGlyphError):
+    pass
+
+
+class RateLimitError(MailGlyphError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        payload: Any = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, payload=payload)
+        self.retry_after = retry_after
+
+
+class ApiError(MailGlyphError):
+    pass

mailglyph/http_client.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from typing import Any
+
+import httpx
+
+from ._version import __version__
+from .exceptions import (
+    ApiError,
+    AuthenticationError,
+    MailGlyphError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+DEFAULT_BASE_URL = "https://api.mailglyph.com"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+
+
+class HttpClient:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._key_type = self._detect_key_type(api_key)
+        headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": f"mailglyph-python/{__version__}",
+        }
+        self._sync_client = httpx.Client(
+            base_url=self._base_url, timeout=self._timeout, headers=headers
+        )
+        self._async_client = httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=self._timeout,
+            headers=headers,
+        )
+
+    @property
+    def key_type(self) -> str:
+        return self._key_type
+
+    @staticmethod
+    def _detect_key_type(api_key: str) -> str:
+        if api_key.startswith("sk_"):
+            return "sk"
+        if api_key.startswith("pk_"):
+            return "pk"
+        raise AuthenticationError("Invalid API key format. Expected key prefix 'sk_' or 'pk_'.")
+
+    def _enforce_key_restrictions(self, path: str) -> None:
+        if self._key_type == "pk" and path != "/v1/track":
+            raise AuthenticationError("Public API keys (pk_*) can only be used with /v1/track.")
+        if self._key_type == "sk" and path == "/v1/track":
+            raise AuthenticationError("Secret API keys (sk_*) cannot be used with /v1/track.")
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+    ) -> Any:
+        self._enforce_key_restrictions(path)
+        return self._request_with_retries(method, path, params=params, json_body=json_body)
+
+    async def arequest(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+    ) -> Any:
+        self._enforce_key_restrictions(path)
+        return await self._arequest_with_retries(method, path, params=params, json_body=json_body)
+
+    def _request_with_retries(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None,
+        json_body: dict[str, Any] | None,
+    ) -> Any:
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._sync_client.request(method, path, params=params, json=json_body)
+            except httpx.TransportError as exc:
+                if attempt >= self._max_retries:
+                    raise ApiError(f"Request failed: {exc}") from exc
+                time.sleep(self._retry_delay(attempt, None))
+                continue
+
+            if self._should_retry(response.status_code) and attempt < self._max_retries:
+                time.sleep(self._retry_delay(attempt, response.headers.get("Retry-After")))
+                continue
+
+            return self._parse_response(response)
+
+        raise ApiError("Request retries exhausted.")
+
+    async def _arequest_with_retries(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None,
+        json_body: dict[str, Any] | None,
+    ) -> Any:
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._async_client.request(
+                    method, path, params=params, json=json_body
+                )
+            except httpx.TransportError as exc:
+                if attempt >= self._max_retries:
+                    raise ApiError(f"Request failed: {exc}") from exc
+                await asyncio.sleep(self._retry_delay(attempt, None))
+                continue
+
+            if self._should_retry(response.status_code) and attempt < self._max_retries:
+                await asyncio.sleep(self._retry_delay(attempt, response.headers.get("Retry-After")))
+                continue
+
+            return self._parse_response(response)
+
+        raise ApiError("Request retries exhausted.")
+
+    @staticmethod
+    def _should_retry(status_code: int) -> bool:
+        return status_code == 429 or 500 <= status_code <= 599
+
+    @staticmethod
+    def _retry_delay(attempt: int, retry_after: str | None) -> float:
+        if retry_after is not None:
+            try:
+                return max(float(retry_after), 0.0)
+            except ValueError:
+                pass
+        base = float(2**attempt)
+        jitter = random.uniform(0.0, 0.2)
+        return base + jitter
+
+    def _parse_response(self, response: httpx.Response) -> Any:
+        if response.status_code >= 400:
+            self._raise_for_status(response)
+
+        if response.status_code == 204:
+            return None
+
+        if not response.content:
+            return None
+
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        payload: Any
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+
+        message = self._extract_error_message(response.status_code, payload, response.text)
+        status_code = response.status_code
+
+        if status_code == 400:
+            raise ValidationError(message, status_code=status_code, payload=payload)
+        if status_code == 401:
+            raise AuthenticationError(message, status_code=status_code, payload=payload)
+        if status_code == 404:
+            raise NotFoundError(message, status_code=status_code, payload=payload)
+        if status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            retry_after_seconds: float | None = None
+            if retry_after is not None:
+                try:
+                    retry_after_seconds = float(retry_after)
+                except ValueError:
+                    retry_after_seconds = None
+            raise RateLimitError(
+                message,
+                status_code=status_code,
+                payload=payload,
+                retry_after=retry_after_seconds,
+            )
+        if 500 <= status_code <= 599:
+            raise ApiError(message, status_code=status_code, payload=payload)
+
+        raise MailGlyphError(message, status_code=status_code, payload=payload)
+
+    @staticmethod
+    def _extract_error_message(status_code: int, payload: Any, fallback: str) -> str:
+        if isinstance(payload, dict):
+            message = payload.get("message")
+            if isinstance(message, str) and message:
+                return message
+            error = payload.get("error")
+            if isinstance(error, str) and error:
+                return error
+        if fallback:
+            return fallback
+        return f"Request failed with status code {status_code}."
+
+    def close(self) -> None:
+        self._sync_client.close()
+
+    async def aclose(self) -> None:
+        await self._async_client.aclose()

mailglyph/models.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
+
+
+class MailGlyphModel(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class ContactRef(MailGlyphModel):
+    id: str
+    email: str
+
+
+class SendEmailItem(MailGlyphModel):
+    contact: ContactRef
+    email: str
+
+
+class SendEmailResult(MailGlyphModel):
+    emails: list[SendEmailItem] = Field(default_factory=list)
+    timestamp: str | None = None
+
+
+class VerifyEmailResult(MailGlyphModel):
+    email: str
+    valid: bool
+    is_disposable: bool = Field(alias="isDisposable")
+    is_alias: bool = Field(alias="isAlias")
+    is_typo: bool = Field(alias="isTypo")
+    is_plus_addressed: bool = Field(alias="isPlusAddressed")
+    is_random_input: bool = Field(alias="isRandomInput")
+    is_personal_email: bool = Field(alias="isPersonalEmail")
+    domain_exists: bool = Field(alias="domainExists")
+    has_website: bool = Field(alias="hasWebsite")
+    has_mx_records: bool = Field(alias="hasMxRecords")
+    suggested_email: str | None = Field(default=None, alias="suggestedEmail")
+    reasons: list[str] = Field(default_factory=list)
+
+
+class TrackEventResult(MailGlyphModel):
+    contact: str
+    event: str
+    timestamp: str
+
+
+class ContactMeta(MailGlyphModel):
+    is_new: bool | None = Field(default=None, alias="isNew")
+    is_update: bool | None = Field(default=None, alias="isUpdate")
+
+
+class Contact(MailGlyphModel):
+    id: str
+    email: str
+    subscribed: bool
+    data: dict[str, Any] = Field(default_factory=dict)
+    created_at: str | None = Field(default=None, alias="createdAt")
+    updated_at: str | None = Field(default=None, alias="updatedAt")
+    meta: ContactMeta | None = Field(default=None, alias="_meta")
+
+
+class Segment(MailGlyphModel):
+    id: str
+    name: str | None = None
+    description: str | None = None
+    condition: FilterCondition | None = None
+    track_membership: bool | None = Field(default=None, alias="trackMembership")
+    member_count: int | None = Field(default=None, alias="memberCount")
+    project_id: str | None = Field(default=None, alias="projectId")
+    created_at: str | None = Field(default=None, alias="createdAt")
+    updated_at: str | None = Field(default=None, alias="updatedAt")
+
+
+class SegmentFilter(MailGlyphModel):
+    field: str
+    operator: str
+    value: Any | None = None
+    unit: str | None = None
+
+
+class FilterGroup(MailGlyphModel):
+    filters: list[SegmentFilter] = Field(default_factory=list)
+    conditions: FilterCondition | None = None
+
+
+class FilterCondition(MailGlyphModel):
+    logic: str
+    groups: list[FilterGroup] = Field(default_factory=list)
+
+
+class Campaign(MailGlyphModel):
+    id: str
+    name: str | None = None
+    description: str | None = None
+    subject: str | None = None
+    body: str | None = None
+    from_email: str | None = Field(default=None, alias="from")
+    from_name: str | None = Field(default=None, alias="fromName")
+    reply_to: str | None = Field(default=None, alias="replyTo")
+    audience_type: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("audienceType", "type"),
+        serialization_alias="audienceType",
+    )
+    audience_condition: FilterCondition | None = Field(default=None, alias="audienceCondition")
+    segment_id: str | None = Field(default=None, alias="segmentId")
+    status: str | None = None
+    total_recipients: int | None = Field(default=None, alias="totalRecipients")
+    sent_count: int | None = Field(default=None, alias="sentCount")
+    delivered_count: int | None = Field(default=None, alias="deliveredCount")
+    opened_count: int | None = Field(default=None, alias="openedCount")
+    clicked_count: int | None = Field(default=None, alias="clickedCount")
+    bounced_count: int | None = Field(default=None, alias="bouncedCount")
+    scheduled_for: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("scheduledFor", "scheduledAt"),
+        serialization_alias="scheduledFor",
+    )
+    sent_at: str | None = Field(default=None, alias="sentAt")
+    created_at: str | None = Field(default=None, alias="createdAt")
+    updated_at: str | None = Field(default=None, alias="updatedAt")
+    segment: Segment | None = None
+
+
+class ContactsPage(MailGlyphModel):
+    contacts: list[Contact] = Field(default_factory=list)
+    cursor: str | None = None
+    has_more: bool = Field(default=False, alias="hasMore")
+    total: int | None = None
+
+
+class CampaignsPage(MailGlyphModel):
+    data: list[Campaign] = Field(default_factory=list)
+    page: int | None = None
+    page_size: int | None = Field(default=None, alias="pageSize")
+    total: int | None = None
+    total_pages: int | None = Field(default=None, alias="totalPages")
+
+    @property
+    def campaigns(self) -> list[Campaign]:
+        return self.data
+
+
+class SegmentContactsPage(MailGlyphModel):
+    data: list[Contact] = Field(default_factory=list)
+    total: int | None = None
+    page: int | None = None
+    page_size: int | None = Field(default=None, alias="pageSize")
+    total_pages: int | None = Field(default=None, alias="totalPages")
+
+
+class StaticSegmentMembersAddResult(MailGlyphModel):
+    added: int
+    not_found: list[str] = Field(default_factory=list, alias="notFound")
+
+
+class StaticSegmentMembersRemoveResult(MailGlyphModel):
+    removed: int
+
+
+FilterCondition.model_rebuild()

mailglyph/resources/__init__.py

@@ -0,0 +1,18 @@
+from .campaigns import AsyncCampaignsResource, CampaignsResource
+from .contacts import AsyncContactsResource, ContactsResource
+from .emails import AsyncEmailsResource, EmailsResource
+from .events import AsyncEventsResource, EventsResource
+from .segments import AsyncSegmentsResource, SegmentsResource
+
+__all__ = [
+    "AsyncCampaignsResource",
+    "AsyncContactsResource",
+    "AsyncEmailsResource",
+    "AsyncEventsResource",
+    "AsyncSegmentsResource",
+    "CampaignsResource",
+    "ContactsResource",
+    "EmailsResource",
+    "EventsResource",
+    "SegmentsResource",
+]

mailglyph/resources/_utils.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def compact_dict(payload: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in payload.items() if value is not None}
+
+
+def unwrap_data(payload: Any) -> Any:
+    if isinstance(payload, dict) and "data" in payload:
+        return payload["data"]
+    return payload