poststack 0.4.0__py3-none-any.whl

poststack/types.py

@@ -0,0 +1,511 @@
+"""Pydantic models mirroring the PostStack API response shapes.
+
+Models are intentionally compact: JSON blobs (headers, metadata, properties,
+trigger config, step config) use ``Dict[str, Any]`` rather than re-deriving
+every possible field.
+
+All resource methods currently return raw ``dict`` objects parsed from JSON
+(for forward compatibility with API additions). These models are exported for
+callers who want to validate/convert manually, e.g.::
+
+    from poststack.types import Email
+    raw = client.emails.get("em_123")
+    email = Email.model_validate(raw)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# ---------------------------------------------------------------------------
+# Literal enums (strings in the API)
+# ---------------------------------------------------------------------------
+
+EmailStatus = Literal[
+    "queued", "sending", "delivered", "bounced", "complained", "failed"
+]
+EmailEventType = Literal[
+    "queued",
+    "sent",
+    "delivered",
+    "bounced",
+    "soft_bounced",
+    "opened",
+    "clicked",
+    "complained",
+    "unsubscribed",
+    "failed",
+]
+DomainStatus = Literal["pending", "verified", "failed"]
+TlsMode = Literal["opportunistic", "enforced"]
+Region = Literal["eu-west-1", "us-east-1", "sa-east-1", "ap-northeast-1"]
+DnsRecordType = Literal["TXT", "CNAME", "MX", "SRV"]
+DnsPurpose = Literal["spf", "dkim", "dmarc", "return_path", "mx", "imap"]
+BroadcastStatus = Literal["draft", "queued", "sending", "sent", "cancelled"]
+SuppressionReason = Literal["hard_bounce", "complaint", "manual", "unsubscribe"]
+ApiKeyPermission = Literal["full_access", "sending_access"]
+ApiKeyMode = Literal["live", "test"]
+MailboxStatus = Literal["active", "suspended", "deleted"]
+ContactPropertyType = Literal["text", "number", "boolean", "date", "select"]
+WorkflowStatus = Literal["draft", "active", "paused"]
+WorkflowTriggerType = Literal["contact.created", "contact.subscribed", "manual"]
+WorkflowStepType = Literal["send_email", "wait", "condition"]
+WebhookDeliveryStatus = Literal["pending", "success", "failed"]
+EmailValidationResult = Literal[
+    "deliverable", "undeliverable", "risky", "unknown"
+]
+EmailValidationRisk = Literal["low", "medium", "high"]
+SignupFormFieldType = Literal["email", "text", "select", "checkbox"]
+
+
+class _Model(BaseModel):
+    """Base for all models: permissive toward new API fields."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+# ---------------------------------------------------------------------------
+# Shared pagination
+# ---------------------------------------------------------------------------
+
+
+class PaginationMeta(_Model):
+    page: int
+    per_page: int = Field(alias="perPage")
+    total: int
+    total_pages: int = Field(alias="totalPages")
+
+
+# ---------------------------------------------------------------------------
+# TypedDict inputs (what callers pass to send/create/update).
+# Kept permissive; the server is the source of truth for validation.
+# ---------------------------------------------------------------------------
+
+
+class Attachment(TypedDict, total=False):
+    filename: str
+    content: str
+    content_type: str
+
+
+class SendEmailInput(TypedDict, total=False):
+    from_: str
+    to: List[str]
+    cc: List[str]
+    bcc: List[str]
+    reply_to: str
+    subject: str
+    html: str
+    text: str
+    headers: Dict[str, str]
+    tags: List[str]
+    attachments: List[Attachment]
+    idempotency_key: str
+    scheduled_at: str
+    template_id: str
+    variables: Dict[str, str]
+
+
+# ---------------------------------------------------------------------------
+# Email
+# ---------------------------------------------------------------------------
+
+
+class EmailEvent(_Model):
+    type: EmailEventType
+    timestamp: str
+
+
+class Email(_Model):
+    id: str
+    public_id: str = Field(alias="publicId")
+    from_: str = Field(alias="from")
+    to: List[str]
+    subject: str
+    status: EmailStatus
+    created_at: str = Field(alias="createdAt")
+    sent_at: Optional[str] = Field(default=None, alias="sentAt")
+    events: Optional[List[EmailEvent]] = None
+
+
+class EmailInsightWarning(_Model):
+    type: str
+    message: str
+    severity: Literal["low", "medium", "high"]
+
+
+# ---------------------------------------------------------------------------
+# Domain
+# ---------------------------------------------------------------------------
+
+
+class DnsRecord(_Model):
+    type: DnsRecordType
+    name: str
+    value: str
+    purpose: DnsPurpose
+    verified: bool
+
+
+class Domain(_Model):
+    id: int
+    name: str
+    status: DomainStatus
+    region: Region
+    dns_records: List[DnsRecord] = Field(alias="dnsRecords")
+    open_tracking: bool = Field(alias="openTracking")
+    click_tracking: bool = Field(alias="clickTracking")
+    catch_all: bool = Field(alias="catchAll")
+    tls_mode: TlsMode = Field(alias="tlsMode")
+    verified_at: Optional[str] = Field(default=None, alias="verifiedAt")
+    created_at: str = Field(alias="createdAt")
+
+
+class DmarcReport(_Model):
+    id: int
+    org_name: str = Field(alias="orgName")
+    date_range_begin: str = Field(alias="dateRangeBegin")
+    date_range_end: str = Field(alias="dateRangeEnd")
+    total_count: int = Field(alias="totalCount")
+    pass_count: int = Field(alias="passCount")
+    fail_count: int = Field(alias="failCount")
+
+
+class DmarcStats(_Model):
+    total_messages: int = Field(alias="totalMessages")
+    pass_rate: float = Field(alias="passRate")
+    failed_messages: int = Field(alias="failedMessages")
+    daily_stats: List[Dict[str, Any]] = Field(alias="dailyStats")
+
+
+class DmarcSource(_Model):
+    source_ip: str = Field(alias="sourceIp")
+    org_name: Optional[str] = Field(default=None, alias="orgName")
+    count: int
+    pass_count: int = Field(alias="passCount")
+    fail_count: int = Field(alias="failCount")
+
+
+# ---------------------------------------------------------------------------
+# Contact
+# ---------------------------------------------------------------------------
+
+
+class Contact(_Model):
+    id: str
+    email: str
+    first_name: Optional[str] = Field(default=None, alias="firstName")
+    last_name: Optional[str] = Field(default=None, alias="lastName")
+    unsubscribed: bool
+    properties: Optional[Dict[str, Any]] = None
+    created_at: str = Field(alias="createdAt")
+
+
+class ContactProperty(_Model):
+    id: int
+    name: str
+    label: str
+    type: ContactPropertyType
+    options: Optional[List[str]] = None
+    required: bool
+    created_at: str = Field(alias="createdAt")
+
+
+class ImportContactsResult(_Model):
+    imported: int
+    updated: int
+    skipped: int
+    errors: List[Dict[str, str]]
+
+
+# ---------------------------------------------------------------------------
+# Segment
+# ---------------------------------------------------------------------------
+
+
+class Segment(_Model):
+    id: str
+    name: str
+    contact_count: int = Field(alias="contactCount")
+    created_at: str = Field(alias="createdAt")
+
+
+class SegmentPreviewResult(_Model):
+    count: int
+    sample: List[Contact]
+
+
+# ---------------------------------------------------------------------------
+# Template
+# ---------------------------------------------------------------------------
+
+
+class Template(_Model):
+    id: int
+    public_id: str = Field(alias="publicId")
+    name: str
+    subject: str
+    html_body: Optional[str] = Field(default=None, alias="htmlBody")
+    text_body: Optional[str] = Field(default=None, alias="textBody")
+    variables: Optional[List[str]] = None
+    published: bool
+    version: int
+    created_at: str = Field(alias="createdAt")
+
+
+class TemplatePreset(_Model):
+    id: str
+    name: str
+    description: Optional[str] = None
+    thumbnail: Optional[str] = None
+    subject: str
+    html: str
+    text: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Webhook
+# ---------------------------------------------------------------------------
+
+
+class Webhook(_Model):
+    id: int
+    url: str
+    events: List[str]
+    active: bool
+    created_at: str = Field(alias="createdAt")
+
+
+class WebhookDelivery(_Model):
+    id: int
+    webhook_id: int = Field(alias="webhookId")
+    event: str
+    status_code: Optional[int] = Field(default=None, alias="statusCode")
+    success: bool
+    attempts: int
+    created_at: str = Field(alias="createdAt")
+    next_attempt_at: Optional[str] = Field(default=None, alias="nextAttemptAt")
+
+
+# ---------------------------------------------------------------------------
+# Broadcast
+# ---------------------------------------------------------------------------
+
+
+class Broadcast(_Model):
+    id: int
+    public_id: str = Field(alias="publicId")
+    subject: str
+    status: BroadcastStatus
+    total_recipients: int = Field(alias="totalRecipients")
+    delivered_count: int = Field(alias="deliveredCount")
+    opened_count: int = Field(alias="openedCount")
+    clicked_count: int = Field(alias="clickedCount")
+    bounced_count: int = Field(alias="bouncedCount")
+    created_at: str = Field(alias="createdAt")
+    sent_at: Optional[str] = Field(default=None, alias="sentAt")
+    scheduled_at: Optional[str] = Field(default=None, alias="scheduledAt")
+
+
+class BroadcastVariant(_Model):
+    id: int
+    name: str
+    subject: str
+    weight: int
+    delivered_count: int = Field(alias="deliveredCount")
+    opened_count: int = Field(alias="openedCount")
+    clicked_count: int = Field(alias="clickedCount")
+
+
+class BroadcastVariantStats(_Model):
+    variants: List[BroadcastVariant]
+    winner: Optional[Dict[str, Any]] = None
+
+
+# ---------------------------------------------------------------------------
+# Suppression
+# ---------------------------------------------------------------------------
+
+
+class Suppression(_Model):
+    id: int
+    email: str
+    reason: SuppressionReason
+    created_at: str = Field(alias="createdAt")
+
+
+# ---------------------------------------------------------------------------
+# API key
+# ---------------------------------------------------------------------------
+
+
+class ApiKey(_Model):
+    id: int
+    name: str
+    key_prefix: str = Field(alias="keyPrefix")
+    permission: ApiKeyPermission
+    mode: ApiKeyMode
+    domain_id: Optional[int] = Field(default=None, alias="domainId")
+    last_used_at: Optional[str] = Field(default=None, alias="lastUsedAt")
+    expires_at: Optional[str] = Field(default=None, alias="expiresAt")
+    created_at: str = Field(alias="createdAt")
+
+
+# ---------------------------------------------------------------------------
+# Mailbox
+# ---------------------------------------------------------------------------
+
+
+class Mailbox(_Model):
+    id: int
+    team_id: int = Field(alias="teamId")
+    domain_id: int = Field(alias="domainId")
+    email_address: str = Field(alias="emailAddress")
+    display_name: Optional[str] = Field(default=None, alias="displayName")
+    quota_bytes: int = Field(alias="quotaBytes")
+    status: MailboxStatus
+    webhook_enabled: bool = Field(alias="webhookEnabled")
+    last_login_at: Optional[str] = Field(default=None, alias="lastLoginAt")
+    created_at: str = Field(alias="createdAt")
+    updated_at: str = Field(alias="updatedAt")
+
+
+class MailboxAlias(_Model):
+    id: int
+    team_id: int = Field(alias="teamId")
+    domain_id: int = Field(alias="domainId")
+    alias_address: str = Field(alias="aliasAddress")
+    destination_mailbox_id: int = Field(alias="destinationMailboxId")
+    created_at: str = Field(alias="createdAt")
+
+
+# ---------------------------------------------------------------------------
+# Subscription topic
+# ---------------------------------------------------------------------------
+
+
+class SubscriptionTopic(_Model):
+    id: int
+    name: str
+    description: Optional[str] = None
+    created_at: str = Field(alias="createdAt")
+
+
+class ContactSubscription(_Model):
+    topic_id: int = Field(alias="topicId")
+    contact_id: int = Field(alias="contactId")
+    subscribed_at: str = Field(alias="subscribedAt")
+
+
+# ---------------------------------------------------------------------------
+# Workflow
+# ---------------------------------------------------------------------------
+
+
+class WorkflowStep(_Model):
+    id: int
+    step_type: WorkflowStepType = Field(alias="stepType")
+    position: int
+    config: Dict[str, Any]
+    created_at: str = Field(alias="createdAt")
+
+
+class Workflow(_Model):
+    id: int
+    public_id: str = Field(alias="publicId")
+    name: str
+    trigger_type: WorkflowTriggerType = Field(alias="triggerType")
+    trigger_config: Optional[Dict[str, Any]] = Field(
+        default=None, alias="triggerConfig"
+    )
+    status: WorkflowStatus
+    steps: Optional[List[WorkflowStep]] = None
+    created_at: str = Field(alias="createdAt")
+    updated_at: str = Field(alias="updatedAt")
+
+
+# ---------------------------------------------------------------------------
+# Signup form
+# ---------------------------------------------------------------------------
+
+
+class SignupFormField(_Model):
+    name: str
+    type: SignupFormFieldType
+    label: str
+    required: Optional[bool] = None
+    options: Optional[List[str]] = None
+
+
+class SignupForm(_Model):
+    id: int
+    public_id: str = Field(alias="publicId")
+    name: str
+    segment_id: Optional[int] = Field(default=None, alias="segmentId")
+    topic_id: Optional[int] = Field(default=None, alias="topicId")
+    fields: List[SignupFormField]
+    success_message: Optional[str] = Field(
+        default=None, alias="successMessage"
+    )
+    redirect_url: Optional[str] = Field(default=None, alias="redirectUrl")
+    active: bool
+    submission_count: int = Field(alias="submissionCount")
+    created_at: str = Field(alias="createdAt")
+    updated_at: str = Field(alias="updatedAt")
+
+
+# ---------------------------------------------------------------------------
+# Email validation
+# ---------------------------------------------------------------------------
+
+
+class EmailValidation(_Model):
+    email: str
+    result: EmailValidationResult
+    syntax_valid: bool = Field(alias="syntaxValid")
+    mx_valid: bool = Field(alias="mxValid")
+    is_disposable: bool = Field(alias="isDisposable")
+    is_role: bool = Field(alias="isRole")
+    is_free: bool = Field(alias="isFree")
+    risk: EmailValidationRisk
+
+
+__all__ = [
+    "PaginationMeta",
+    "Attachment",
+    "SendEmailInput",
+    "EmailEvent",
+    "Email",
+    "EmailInsightWarning",
+    "DnsRecord",
+    "Domain",
+    "DmarcReport",
+    "DmarcStats",
+    "DmarcSource",
+    "Contact",
+    "ContactProperty",
+    "ImportContactsResult",
+    "Segment",
+    "SegmentPreviewResult",
+    "Template",
+    "TemplatePreset",
+    "Webhook",
+    "WebhookDelivery",
+    "Broadcast",
+    "BroadcastVariant",
+    "BroadcastVariantStats",
+    "Suppression",
+    "ApiKey",
+    "Mailbox",
+    "MailboxAlias",
+    "SubscriptionTopic",
+    "ContactSubscription",
+    "WorkflowStep",
+    "Workflow",
+    "SignupFormField",
+    "SignupForm",
+    "EmailValidation",
+]

poststack-0.4.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: poststack
+Version: 0.4.0
+Summary: Official Python SDK for the PostStack Email API
+Project-URL: Homepage, https://poststack.dev
+Project-URL: Documentation, https://poststack.dev/docs
+Project-URL: Repository, https://github.com/getpoststack/python-sdk
+Project-URL: Issues, https://github.com/getpoststack/python-sdk/issues
+Author: PostStack
+License: MIT
+License-File: LICENSE
+Keywords: api,email,poststack,smtp,transactional
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PostStack Python SDK
+
+Official Python SDK for the [PostStack](https://poststack.dev) Email API —
+an [EU-hosted, GDPR-compliant](https://poststack.dev/security)
+[email API for Python](https://poststack.dev) with sync and async clients,
+full type hints, and drop-in compatibility with Django, FastAPI, Flask,
+and Starlette. Up to 75% cheaper than Resend, SendGrid, and Postmark.
+
+Docs: [poststack.dev/docs/sdk](https://poststack.dev/docs/sdk).
+
+## Installation
+
+```bash
+pip install poststack
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+from poststack import PostStack
+
+client = PostStack(api_key="sk_live_...")
+
+result = client.emails.send({
+    "from": "hello@example.com",
+    "to": ["user@example.com"],
+    "subject": "Hello from PostStack",
+    "html": "<p>Welcome!</p>",
+})
+
+print(result["id"])
+```
+
+## Async usage
+
+```python
+import asyncio
+from poststack import AsyncPostStack
+
+async def main():
+    client = AsyncPostStack(api_key="sk_live_...")
+    try:
+        result = await client.emails.send({
+            "from": "hello@example.com",
+            "to": ["user@example.com"],
+            "subject": "Hello from PostStack",
+            "html": "<p>Welcome!</p>",
+        })
+        print(result["id"])
+    finally:
+        await client.aclose()
+
+asyncio.run(main())
+```
+
+Or use it as an async context manager:
+
+```python
+async with AsyncPostStack(api_key="sk_live_...") as client:
+    result = await client.emails.send({...})
+```
+
+## Error handling
+
+Any non-2xx response raises `PostStackError`:
+
+```python
+from poststack import PostStack, PostStackError
+
+client = PostStack(api_key="sk_live_...")
+
+try:
+    client.emails.send({"from": "x@y.com", "to": ["z@w.com"], "subject": "hi"})
+except PostStackError as e:
+    print(e.status_code, e.error, e.request_id)
+```
+
+## Configuration
+
+```python
+client = PostStack(
+    api_key="sk_live_...",
+    base_url="https://api.poststack.dev",  # default
+    timeout=30.0,                           # default (seconds)
+)
+```
+
+Override timeout per call:
+
+```python
+client.emails.send({...}, timeout=60.0)
+```
+
+## Resources
+
+- `client.emails` — send, get, list, cancel, reschedule, batch, events, insights
+- `client.domains` — create, list, get, verify, update, delete, DMARC
+- `client.contacts` — CRUD, import, export, unsubscribe
+- `client.contact_properties` — custom properties
+- `client.segments` — create, list, get, update, delete, contacts, preview
+- `client.templates` — CRUD, publish, duplicate, presets
+- `client.webhooks` — CRUD, test, deliveries, replay
+- `client.broadcasts` — CRUD, send, test, variants
+- `client.suppressions` — list, add, remove
+- `client.api_keys` — CRUD
+- `client.mailboxes` — CRUD, aliases, password
+- `client.subscription_topics` — topics + contact subscriptions
+- `client.workflows` — CRUD, steps, activate, pause, trigger
+- `client.signup_forms` — CRUD, submit
+- `client.email_validations` — validate, validate_batch
+
+## Links
+
+- [PostStack — EU-hosted email API](https://poststack.dev)
+- [API documentation](https://poststack.dev/docs)
+- [Pricing](https://poststack.dev/pricing) · [Compare providers](https://poststack.dev/pricing/compare)
+- [Migrate from Resend](https://poststack.dev/migrate/resend) · [from SendGrid](https://poststack.dev/migrate/sendgrid) · [from Postmark](https://poststack.dev/migrate/postmark)
+- [Status](https://poststack.dev/status) · [Security](https://poststack.dev/security) · [DPA](https://poststack.dev/dpa)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

poststack-0.4.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+poststack/__init__.py,sha256=_ehy6cQ1ozYlDUh8iyZhLHFJSAvSX8sRSS2tQopjMNw,4857
+poststack/_client.py,sha256=82_v2DbcfNEmUVfrjl33NdYq4_uGdcfJbY3QPimfzNU,9860
+poststack/_errors.py,sha256=X8qQ4xaIsetDB8uDgxVEPRBOAhOSJrR5rmFs_UPBacI,894
+poststack/types.py,sha256=ecBtZnAxkbgtPZ1vq2nRnd-RrsYAJKoFfSwhWFKwDqw,15019
+poststack/resources/__init__.py,sha256=myTAQKQ29s6hVUutb1H8Z-SHgLV1MQQizen3XOA53dQ,2023
+poststack/resources/api_keys.py,sha256=a3t1HNezQyXcaL02DAIFaFQBC_90eROmgcaUJJcSKkI,2000
+poststack/resources/broadcasts.py,sha256=JZ8HAPG9rYG_euXpBN6lZ1eSZ5RE0_gdRmkNK9_uT6A,4747
+poststack/resources/contact_properties.py,sha256=HmYh3OqMiESQJMiFxwKbyAR35oWgHdia_UjziDoq7BI,2197
+poststack/resources/contacts.py,sha256=FDlNi36_3cN9uXKG5I1KWMNlwIl92FE1Qfof4BcYIuQ,3988
+poststack/resources/domains.py,sha256=HAa15Oy3VBN5K_7MRe0XLapKBgu6T7OjMx7vyTT-YZI,5848
+poststack/resources/email_validations.py,sha256=K-Vc3Ky1vNkjcOL9599rRkj5teW02ZuH8IBog4mOXbI,1498
+poststack/resources/emails.py,sha256=53eQbSYyMnp5qWaIVv5TwB8CiS4RHGyw1TjuAqcqQAo,3993
+poststack/resources/mailboxes.py,sha256=B2Nh60duCI5juwNAzpPHTb5x0D-u0OKhW1pd8qcFLD0,4570
+poststack/resources/segments.py,sha256=CarkZsrOv1-DmzcNvggXPKOG5Id9mdOL8vDQ47QE7z4,4451
+poststack/resources/signup_forms.py,sha256=7LJpORwi6Ihno5B-wuOXhA8-XzycqUnZeUW5YrIXXb4,3461
+poststack/resources/subscription_topics.py,sha256=VOW4oaI0LAhWSgsZ3KFvtzuPfLnpxFOny36TljcEGTY,3589
+poststack/resources/suppressions.py,sha256=P6sp1YXXLjIw4n5DAlDo23fSJKC4mROSUSuyk3ZJcq8,1835
+poststack/resources/templates.py,sha256=Lc2-2UFGNYXO8WBnOKaiB7s-Q0-wBjhbGP8Ty1h7elo,4953
+poststack/resources/webhooks.py,sha256=4X8u7h-X18HAUcGSgEMZ9FwuXenjYAXN4aEOUzDc3GE,4044
+poststack/resources/workflows.py,sha256=kpqAOjDjRs-Xqxor744f4Hr6QRLtNalHmHuoKJDSQas,5397
+poststack-0.4.0.dist-info/METADATA,sha256=0l7BeA7nLr3axFChqjpy9dC5-mquWRHNug6FU6Wmh7Y,4771
+poststack-0.4.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+poststack-0.4.0.dist-info/licenses/LICENSE,sha256=xQFLbiPx_5D3Zh06D12XhGi_DHvRNsJMz2z7_JHGLO0,1074
+poststack-0.4.0.dist-info/RECORD,,

poststack-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any