mailblastr 1.0.0__py3-none-any.whl

mailblastr/__init__.py

@@ -0,0 +1,74 @@
+"""Official MailBlastr Python SDK.
+
+Usage::
+
+    import mailblastr
+    mailblastr.api_key = "mb_xxxxxxxxx"
+
+    email = mailblastr.Emails.send({
+        "from": "Acme <hello@yourdomain.com>",
+        "to": ["user@example.com"],
+        "subject": "Hello from MailBlastr",
+        "html": "<p>Your first email</p>",
+    })
+
+Every method returns the parsed JSON response and raises
+:class:`mailblastr.MailblastrError` on any non-2xx status.
+"""
+
+from typing import Optional
+
+from .http_client import DEFAULT_BASE_URL, USER_AGENT, VERSION
+from .exceptions import MailblastrError
+from .emails import Emails
+from .batch import Batch
+from .domains import Domains
+from .audiences import Audiences
+from .contacts import Contacts
+from .contact_properties import ContactProperties
+from .campaigns import Campaigns
+from .segments import Segments
+from .topics import Topics
+from .templates import Templates
+from .automations import Automations
+from .webhooks import Webhooks, verify_webhook_signature
+from .events import Events
+from .api_keys import ApiKeys
+from .logs import Logs
+from .polls import Polls
+
+# ---- Module-level configuration (resend-python style) ----
+
+# Your MailBlastr API key, e.g. mailblastr.api_key = "mb_xxxxxxxxx"
+api_key: Optional[str] = None
+
+# Override to point at a different API host.
+base_url: str = DEFAULT_BASE_URL
+
+__version__ = VERSION
+
+__all__ = [
+    "api_key",
+    "base_url",
+    "MailblastrError",
+    "verify_webhook_signature",
+    "Emails",
+    "Batch",
+    "Domains",
+    "Audiences",
+    "Contacts",
+    "ContactProperties",
+    "Campaigns",
+    "Segments",
+    "Topics",
+    "Templates",
+    "Automations",
+    "Webhooks",
+    "Events",
+    "ApiKeys",
+    "Logs",
+    "Polls",
+    "DEFAULT_BASE_URL",
+    "USER_AGENT",
+    "VERSION",
+]

mailblastr/api_keys.py

@@ -0,0 +1,34 @@
+"""API keys resource."""
+
+from typing import TypedDict
+
+from . import http_client
+from .http_client import path_escape as _e
+
+
+class CreateParams(TypedDict, total=False):
+    name: str  # required
+    permission: str  # 'full_access' | 'sending_access'
+    domain_id: str  # scope a sending_access key to one domain
+
+
+class ApiKeys:
+    """``mailblastr.ApiKeys`` — the /api-keys endpoints."""
+
+    CreateParams = CreateParams
+
+    @classmethod
+    def create(cls, params):
+        """Create an API key. The full token is returned ONLY here.
+        POST /api-keys"""
+        return http_client.request("POST", "/api-keys", params)
+
+    @classmethod
+    def list(cls):
+        """List API keys (non-secret prefixes only). GET /api-keys"""
+        return http_client.request("GET", "/api-keys")
+
+    @classmethod
+    def remove(cls, api_key_id):
+        """Delete an API key. DELETE /api-keys/:id"""
+        return http_client.request("DELETE", f"/api-keys/{_e(api_key_id)}")

mailblastr/audiences.py

@@ -0,0 +1,56 @@
+"""Audiences resource (incl. Google Sheet contact import)."""
+
+from typing import TypedDict
+
+from . import http_client
+from .http_client import paginate, path_escape as _e
+
+
+class CreateParams(TypedDict):
+    name: str
+
+
+class ImportSheetParams(TypedDict, total=False):
+    url: str  # required: link-shared Google Sheet URL
+    segment_name: str
+
+
+class Audiences:
+    """``mailblastr.Audiences`` — the /audiences endpoints."""
+
+    CreateParams = CreateParams
+    ImportSheetParams = ImportSheetParams
+
+    @classmethod
+    def create(cls, params):
+        """Create an audience. POST /audiences"""
+        return http_client.request("POST", "/audiences", params)
+
+    @classmethod
+    def get(cls, audience_id):
+        """Retrieve an audience. GET /audiences/:id"""
+        return http_client.request("GET", f"/audiences/{_e(audience_id)}")
+
+    @classmethod
+    def list(cls, params=None):
+        """List audiences. GET /audiences"""
+        return http_client.request("GET", f"/audiences{paginate(params)}")
+
+    @classmethod
+    def update(cls, audience_id, params):
+        """Rename an audience. PATCH /audiences/:id"""
+        return http_client.request("PATCH", f"/audiences/{_e(audience_id)}", params)
+
+    @classmethod
+    def import_sheet(cls, audience_id, params):
+        """Import contacts from a link-shared Google Sheet. Header columns
+        become contact properties (usable as ``{{merge_tags}}``); rows land in
+        a fresh segment. POST /audiences/:id/contacts/import-sheet"""
+        return http_client.request(
+            "POST", f"/audiences/{_e(audience_id)}/contacts/import-sheet", params
+        )
+
+    @classmethod
+    def remove(cls, audience_id):
+        """Delete an audience. DELETE /audiences/:id"""
+        return http_client.request("DELETE", f"/audiences/{_e(audience_id)}")

mailblastr/automations.py

@@ -0,0 +1,98 @@
+"""Automations resource — DOMAIN-FIRST: every automation belongs to one of
+your sending domains (``domain`` is REQUIRED on create). Only ``Events.send``
+calls with the same ``domain`` trigger it."""
+
+from typing import Any, Dict, List, TypedDict
+
+from . import http_client
+from .http_client import paginate, path_escape as _e
+
+
+class CreateParams(TypedDict, total=False):
+    name: str  # required
+    domain: str  # REQUIRED: the sending domain this automation belongs to
+    trigger: str  # e.g. 'contact.created', 'email.opened', or a custom event name
+    status: str  # 'enabled' | 'disabled' (default 'disabled')
+    steps: List[Dict[str, Any]]  # optional inline step graph
+    connections: List[Dict[str, str]]  # optional typed edges between step keys
+
+
+class UpdateParams(TypedDict, total=False):
+    name: str
+    status: str  # 'enabled' | 'disabled'
+    domain: str  # re-point at another domain (disabled automations only)
+    connections: List[Dict[str, str]]
+
+
+class AddStepParams(TypedDict, total=False):
+    type: str  # required, e.g. 'send_email' | 'wait' | 'condition'
+    config: Dict[str, Any]
+    key: str
+
+
+class Automations:
+    """``mailblastr.Automations`` — the /automations endpoints."""
+
+    CreateParams = CreateParams
+    UpdateParams = UpdateParams
+    AddStepParams = AddStepParams
+
+    @classmethod
+    def create(cls, params):
+        """Create an automation (``domain`` is required). POST /automations"""
+        return http_client.request("POST", "/automations", params)
+
+    @classmethod
+    def get(cls, automation_id):
+        """Retrieve an automation (with steps/connections/enrollments).
+        GET /automations/:id"""
+        return http_client.request("GET", f"/automations/{_e(automation_id)}")
+
+    @classmethod
+    def list(cls, params=None):
+        """List automations. GET /automations"""
+        return http_client.request("GET", f"/automations{paginate(params)}")
+
+    @classmethod
+    def update(cls, automation_id, params):
+        """Update an automation. PATCH /automations/:id"""
+        return http_client.request("PATCH", f"/automations/{_e(automation_id)}", params)
+
+    @classmethod
+    def add_step(cls, automation_id, params):
+        """Append a step to an automation. POST /automations/:id/steps"""
+        return http_client.request("POST", f"/automations/{_e(automation_id)}/steps", params)
+
+    @classmethod
+    def delete_step(cls, automation_id, step_id):
+        """Delete a step from an automation.
+        DELETE /automations/:id/steps/:step_id"""
+        return http_client.request(
+            "DELETE", f"/automations/{_e(automation_id)}/steps/{_e(step_id)}"
+        )
+
+    @classmethod
+    def runs(cls, automation_id, params=None):
+        """List an automation's runs. GET /automations/:id/runs"""
+        return http_client.request(
+            "GET", f"/automations/{_e(automation_id)}/runs{paginate(params)}"
+        )
+
+    @classmethod
+    def get_run(cls, automation_id, run_id):
+        """Retrieve a single automation run (with its step trace).
+        GET /automations/:id/runs/:run_id"""
+        return http_client.request(
+            "GET", f"/automations/{_e(automation_id)}/runs/{_e(run_id)}"
+        )
+
+    @classmethod
+    def stop(cls, automation_id):
+        """Stop an automation — prevents new runs; in-progress runs finish.
+        POST /automations/:id/stop"""
+        return http_client.request("POST", f"/automations/{_e(automation_id)}/stop")
+
+    @classmethod
+    def remove(cls, automation_id):
+        """Delete an automation. DELETE /automations/:id"""
+        return http_client.request("DELETE", f"/automations/{_e(automation_id)}")

mailblastr/batch.py

@@ -0,0 +1,14 @@
+"""Batch send resource — ``mailblastr.Batch.send([...])``."""
+
+from . import http_client
+
+
+class Batch:
+    """``mailblastr.Batch`` — the /emails/batch endpoint."""
+
+    @classmethod
+    def send(cls, params, options=None):
+        """Send up to 100 emails in one request. POST /emails/batch
+
+        ``params`` is a list of :class:`mailblastr.Emails.SendParams` dicts."""
+        return http_client.request("POST", "/emails/batch", params, options)

mailblastr/campaigns.py

@@ -0,0 +1,110 @@
+"""Campaigns resource — bulk sends to a domain's contact pool (DOMAIN-FIRST:
+``domain`` is required on create and picks the contact pool the campaign
+targets; ``from`` may be a different verified domain)."""
+
+from typing import Any, Dict, List, TypedDict, Union
+
+from . import http_client
+from .http_client import paginate, path_escape as _e
+
+CreateParams = TypedDict(
+    "CreateParams",
+    {
+        "domain": str,  # REQUIRED: the sending domain whose contact pool to target
+        "from": str,  # required
+        "subject": str,  # required
+        "html": str,
+        "text": str,
+        "reply_to": Union[str, List[str]],
+        "preview_text": str,
+        "name": str,
+        "segment_id": str,  # target a segment instead of everyone
+        "topic_id": str,  # gate recipients by a topic subscription
+        "recurrence": str,  # 'daily' | 'weekly' | 'monthly'
+        "recurrence_every": int,  # periods between recurring sends (1-365)
+        "ab_test": Dict[str, Any],  # A/B-test configuration
+        "followups": List[Dict[str, Any]],  # engagement follow-ups (max 5)
+        "list_to": bool,
+        "unsubscribe_policy": str,  # 'account' | 'domain' | 'ignore'
+        "send": bool,  # send immediately on create
+        "scheduled_at": str,
+    },
+    total=False,
+)
+
+UpdateParams = TypedDict(
+    "UpdateParams",
+    {
+        "name": str,
+        "from": str,
+        "subject": str,
+        "html": str,
+        "text": str,
+        "reply_to": Union[str, List[str]],
+        "preview_text": str,
+        "domain": str,  # re-point at another domain's pool (draft campaigns only)
+        "segment_id": Union[str, None],
+        "topic_id": Union[str, None],
+        "recurrence": str,
+        "recurrence_every": int,
+        "ab_test": Dict[str, Any],
+    },
+    total=False,
+)
+
+
+class Campaigns:
+    """``mailblastr.Campaigns`` — the /campaigns endpoints."""
+
+    CreateParams = CreateParams
+    UpdateParams = UpdateParams
+
+    @classmethod
+    def create(cls, params):
+        """Create a campaign (``domain`` is required). POST /campaigns"""
+        return http_client.request("POST", "/campaigns", params)
+
+    @classmethod
+    def get(cls, campaign_id):
+        """Retrieve a campaign. GET /campaigns/:id"""
+        return http_client.request("GET", f"/campaigns/{_e(campaign_id)}")
+
+    @classmethod
+    def list(cls, params=None):
+        """List campaigns. GET /campaigns"""
+        return http_client.request("GET", f"/campaigns{paginate(params)}")
+
+    @classmethod
+    def update(cls, campaign_id, params):
+        """Update a campaign. PATCH /campaigns/:id"""
+        return http_client.request("PATCH", f"/campaigns/{_e(campaign_id)}", params)
+
+    @classmethod
+    def send(cls, campaign_id, params=None):
+        """Send now, or schedule with ``{"scheduled_at": ...}``.
+        POST /campaigns/:id/send"""
+        return http_client.request(
+            "POST", f"/campaigns/{_e(campaign_id)}/send", params if params is not None else {}
+        )
+
+    @classmethod
+    def cancel(cls, campaign_id):
+        """Cancel a scheduled campaign (returns it to draft).
+        POST /campaigns/:id/cancel"""
+        return http_client.request("POST", f"/campaigns/{_e(campaign_id)}/cancel")
+
+    @classmethod
+    def stats(cls, campaign_id):
+        """Per-campaign analytics (counts, engagement rates, top links).
+        GET /campaigns/:id/stats"""
+        return http_client.request("GET", f"/campaigns/{_e(campaign_id)}/stats")
+
+    @classmethod
+    def ab(cls, campaign_id):
+        """A/B winner evaluation for an A/B campaign. GET /campaigns/:id/ab"""
+        return http_client.request("GET", f"/campaigns/{_e(campaign_id)}/ab")
+
+    @classmethod
+    def remove(cls, campaign_id):
+        """Delete a campaign. DELETE /campaigns/:id"""
+        return http_client.request("DELETE", f"/campaigns/{_e(campaign_id)}")

mailblastr/contact_properties.py

@@ -0,0 +1,50 @@
+"""Contact properties (custom fields) resource."""
+
+from typing import TypedDict, Union
+
+from . import http_client
+from .http_client import paginate, path_escape as _e
+
+
+class CreateParams(TypedDict, total=False):
+    key: str  # canonical merge-tag key (`name` is accepted as an alias)
+    name: str  # alias for `key`
+    type: str  # required: 'string' | 'number'
+    fallback_value: Union[str, int, float]
+
+
+class UpdateParams(TypedDict, total=False):
+    fallback_value: Union[str, int, float, None]  # only fallback_value is mutable
+
+
+class ContactProperties:
+    """``mailblastr.ContactProperties`` — the /contact-properties endpoints."""
+
+    CreateParams = CreateParams
+    UpdateParams = UpdateParams
+
+    @classmethod
+    def create(cls, params):
+        """Register a custom contact property. POST /contact-properties"""
+        return http_client.request("POST", "/contact-properties", params)
+
+    @classmethod
+    def get(cls, property_id):
+        """Retrieve a contact property. GET /contact-properties/:id"""
+        return http_client.request("GET", f"/contact-properties/{_e(property_id)}")
+
+    @classmethod
+    def list(cls, params=None):
+        """List contact properties. GET /contact-properties"""
+        return http_client.request("GET", f"/contact-properties{paginate(params)}")
+
+    @classmethod
+    def update(cls, property_id, params):
+        """Update a contact property (key/type are immutable).
+        PATCH /contact-properties/:id"""
+        return http_client.request("PATCH", f"/contact-properties/{_e(property_id)}", params)
+
+    @classmethod
+    def remove(cls, property_id):
+        """Delete a contact property. DELETE /contact-properties/:id"""
+        return http_client.request("DELETE", f"/contact-properties/{_e(property_id)}")

mailblastr/contacts.py

@@ -0,0 +1,191 @@
+"""Contacts resource — DOMAIN-FIRST flat /contacts API plus the nested
+/audiences/:id/contacts variants, bulk imports, segment membership and topics.
+
+Domain-first model: each sending domain has its own contact POOL — the same
+address on two domains is two records with separate consent. On the flat
+``/contacts`` API, ``domain`` is REQUIRED to create/list and disambiguates an
+EMAIL id on get/update/remove. Pass ``audience_id`` instead to target a
+specific audience via the nested API.
+"""
+
+from typing import Dict, List, TypedDict, Union
+
+from . import http_client
+from .http_client import build_query, path_escape as _e
+
+
+class CreateParams(TypedDict, total=False):
+    domain: str  # REQUIRED on the flat /contacts API (when audience_id is omitted)
+    audience_id: str  # target a specific audience via the nested API instead
+    email: str  # required
+    first_name: str
+    last_name: str
+    unsubscribed: bool
+    properties: Dict[str, Union[str, int, float]]
+
+
+class UpdateParams(TypedDict, total=False):
+    id: str  # required: contact id OR email
+    domain: str  # disambiguates an EMAIL id across domains (flat API)
+    audience_id: str  # omit for the flat /contacts/:id API
+    first_name: str
+    last_name: str
+    unsubscribed: bool
+    properties: Dict[str, Union[str, int, float]]
+
+
+class ContactInput(TypedDict, total=False):
+    email: str  # required
+    first_name: str
+    last_name: str
+    unsubscribed: bool
+    properties: Dict[str, Union[str, int, float]]
+
+
+class UpdateTopicsParams(TypedDict):
+    topics: List[Dict[str, str]]  # [{"id": ..., "subscription": "opt_in" | "opt_out"}]
+
+
+class Contacts:
+    """``mailblastr.Contacts`` — the /contacts (+ nested audience) endpoints."""
+
+    CreateParams = CreateParams
+    UpdateParams = UpdateParams
+    ContactInput = ContactInput
+    UpdateTopicsParams = UpdateTopicsParams
+
+    @classmethod
+    def create(cls, params):
+        """Create a contact. Domain-first: pass ``domain`` to create in that
+        domain's contact pool via the flat ``/contacts`` API (required there),
+        or ``audience_id`` to target a specific audience via the nested API."""
+        body = dict(params)
+        audience_id = body.pop("audience_id", None)
+        domain = body.pop("domain", None)
+        if audience_id:
+            # The nested audience route derives its pool from the path.
+            return http_client.request("POST", f"/audiences/{_e(audience_id)}/contacts", body)
+        if domain is not None:
+            body["domain"] = domain
+        return http_client.request("POST", "/contacts", body)
+
+    @classmethod
+    def get(cls, params):
+        """Retrieve a contact by id or email — ``{"id", "domain"?, "audience_id"?}``.
+        An id is exact; an EMAIL can exist in several domains' pools, so pass
+        ``domain`` to pick the pool (omitted → the oldest match anywhere)."""
+        cid = _e(params["id"])
+        audience_id = params.get("audience_id")
+        if audience_id:
+            return http_client.request("GET", f"/audiences/{_e(audience_id)}/contacts/{cid}")
+        qs = build_query({"domain": params.get("domain")})
+        return http_client.request("GET", f"/contacts/{cid}{qs}")
+
+    @classmethod
+    def list(cls, params=None):
+        """List contacts. Domain-first: ``domain`` is required on the flat
+        ``/contacts`` list (names the pool); or pass ``audience_id`` for the
+        nested list. ``segment_id`` filters either variant."""
+        params = params or {}
+        audience_id = params.get("audience_id")
+        qs = build_query(
+            {
+                "domain": params.get("domain") if not audience_id else None,
+                "limit": params.get("limit"),
+                "after": params.get("after"),
+                "before": params.get("before"),
+                "segment_id": params.get("segment_id"),
+            }
+        )
+        base = f"/audiences/{_e(audience_id)}/contacts" if audience_id else "/contacts"
+        return http_client.request("GET", f"{base}{qs}")
+
+    @classmethod
+    def batch(cls, params):
+        """Bulk-import contacts from a list — ``{"audience_id", "contacts",
+        "on_conflict"?}``. Upserts by email; max 10,000 per call.
+        ``on_conflict='skip'`` leaves existing contacts untouched.
+        POST /audiences/:id/contacts/batch"""
+        qs = build_query({"on_conflict": params.get("on_conflict")})
+        return http_client.request(
+            "POST",
+            f"/audiences/{_e(params['audience_id'])}/contacts/batch{qs}",
+            {"contacts": params["contacts"]},
+        )
+
+    @classmethod
+    def import_csv(cls, params):
+        """Bulk-import contacts from CSV text — ``{"audience_id", "csv",
+        "on_conflict"?, "create_properties"?}``. Upserts by email. By default
+        every non-builtin CSV column is auto-registered as a custom property;
+        pass ``create_properties=False`` for strict mode.
+        POST /audiences/:id/contacts/import"""
+        qs = build_query(
+            {
+                "on_conflict": params.get("on_conflict"),
+                "create_properties": (
+                    "false" if params.get("create_properties") is False else None
+                ),
+            }
+        )
+        return http_client.request(
+            "POST",
+            f"/audiences/{_e(params['audience_id'])}/contacts/import{qs}",
+            {"csv": params["csv"]},
+        )
+
+    @classmethod
+    def update(cls, params):
+        """Update a contact. On the flat API, pass ``domain`` when ``id`` is
+        an EMAIL (disambiguates across pools). PATCH /contacts/:id"""
+        body = dict(params)
+        cid = _e(body.pop("id"))
+        audience_id = body.pop("audience_id", None)
+        domain = body.pop("domain", None)
+        if audience_id:
+            return http_client.request(
+                "PATCH", f"/audiences/{_e(audience_id)}/contacts/{cid}", body
+            )
+        if domain is not None:
+            body["domain"] = domain
+        return http_client.request("PATCH", f"/contacts/{cid}", body)
+
+    @classmethod
+    def remove(cls, params):
+        """Delete a contact — ``{"id", "domain"?, "audience_id"?}``. On the
+        flat API, pass ``domain`` when ``id`` is an EMAIL."""
+        cid = _e(params["id"])
+        audience_id = params.get("audience_id")
+        if audience_id:
+            return http_client.request("DELETE", f"/audiences/{_e(audience_id)}/contacts/{cid}")
+        qs = build_query({"domain": params.get("domain")})
+        return http_client.request("DELETE", f"/contacts/{cid}{qs}")
+
+    @classmethod
+    def add_to_segment(cls, contact_id, segment_id):
+        """Add a contact to a segment. POST /contacts/:id/segments/:segment_id"""
+        return http_client.request(
+            "POST", f"/contacts/{_e(contact_id)}/segments/{_e(segment_id)}"
+        )
+
+    @classmethod
+    def remove_from_segment(cls, contact_id, segment_id):
+        """Remove a contact from a segment. DELETE /contacts/:id/segments/:segment_id"""
+        return http_client.request(
+            "DELETE", f"/contacts/{_e(contact_id)}/segments/{_e(segment_id)}"
+        )
+
+    @classmethod
+    def list_segments(cls, contact_id):
+        """List the segments a contact belongs to. GET /contacts/:id/segments"""
+        return http_client.request("GET", f"/contacts/{_e(contact_id)}/segments")
+
+    @classmethod
+    def get_topics(cls, contact_id):
+        """Get a contact's topic subscriptions. GET /contacts/:id/topics"""
+        return http_client.request("GET", f"/contacts/{_e(contact_id)}/topics")
+
+    @classmethod
+    def update_topics(cls, contact_id, params):
+        """Update a contact's topic subscriptions. PATCH /contacts/:id/topics"""
+        return http_client.request("PATCH", f"/contacts/{_e(contact_id)}/topics", params)