mailglyph 2.0.0__tar.gz

mailglyph-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+      - name: Ruff
+        run: ruff check .
+      - name: Mypy
+        run: mypy src/
+      - name: Pytest
+        run: pytest
+      - name: Build
+        run: python -m build

mailglyph-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+      - name: Install build
+        run: pip install "build>=1.2"
+      - name: Build package
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mailglyph-2.0.0/.github/workflows/release-please.yml

@@ -0,0 +1,22 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          release-type: python
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}

mailglyph-2.0.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*.so
+.Python
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.dist/
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+.env
+.env.test
+.DS_Store
+docs/*.md

mailglyph-2.0.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "2.0.0"
+}

mailglyph-2.0.0/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+## Project
+This is the official MailGlyph Python SDK. See `./docs/` for the full specification.
+
+## Context Files (read these FIRST)
+1. [sdk-plan.md](./docs/sdk-plan.md) — Shared API spec, all 22 endpoints, auth rules, error hierarchy, testing strategy, release-please setup
+2. [sdk-plan-python.md](./docs/sdk-plan-python.md) — Python-specific implementation plan (structure, Pydantic models, workflows)
+3. [openapi.json](./docs/openapi.json) — OpenAPI 3.0.3 specification (source of truth for schemas)
+
+## Build Order
+1. Scaffold: `pyproject.toml` (name: `mailglyph`), `src/mailglyph/__init__.py`, `.gitignore`
+2. Exceptions (`src/mailglyph/exceptions.py`) — `MailGlyphError`, `AuthenticationError`, `ValidationError`, `NotFoundError`, `RateLimitError`, `ApiError`
+3. Models (`src/mailglyph/models.py`) — Pydantic BaseModel DTOs: `Contact`, `Segment`, `Campaign`, `SendEmailResult`, `VerifyEmailResult`, `TrackEventResult`
+4. HttpClient (`src/mailglyph/http_client.py`) — httpx transport, Bearer auth, JSON parsing, error mapping, retry with exponential backoff for 429/5xx
+5. Client (`src/mailglyph/client.py`) — sync `MailGlyph` + async `AsyncMailGlyph`, accepts API key + config, exposes `.emails`, `.events`, `.contacts`, `.campaigns`, `.segments`
+6. Resources one at a time with pytest tests:
+   - Emails (send, verify) → tests
+   - Events (track with `pk_*` support, get_names) → tests
+   - Contacts (list, create, get, update, delete, count) → tests
+   - Campaigns (list, create, get, update, send, cancel, test, stats) → tests
+   - Segments (list, create, get, update, delete, list_contacts) → tests
+7. CI: [.github/workflows/ci.yml](cci:7://file:///Users/sharo/Library/CloudStorage/Dropbox/Projects/Plunk/plunk/.github/workflows/ci.yml:0:0-0:0), `release-please.yml`, `publish.yml`
+8. README with install + usage examples
+9. Run `pytest` — all tests must pass
+
+## Standards
+- Python 3.9+ with type hints everywhere
+- httpx for HTTP (sync + async with same codebase)
+- Pydantic v2 for models with camelCase aliases
+- pytest + respx for testing with mocked HTTP responses
+- Snake_case method names (`list_contacts`, not `listContacts`)
+- `from_` parameter name to avoid Python `from` keyword collision
+- Conventional Commits for all commit messages

mailglyph-2.0.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## [2.0.0](https://github.com/MailGlyph/mailglyph-python/compare/v1.0.1...v2.0.0) (2026-03-09)
+
+
+### ⚠ BREAKING CHANGES
+
+* Renames the SDK/package branding from Mailrify to MailGlyph.
+
+### Features
+
+* Add `text` field to email sending parameters. ([cf7ae10](https://github.com/MailGlyph/mailglyph-python/commit/cf7ae10cf0bbcc4c79e80f38b75039a00973b367))
+* Implement methods to add and remove contacts from static segments, along with supporting types and documentation. ([03b99ee](https://github.com/MailGlyph/mailglyph-python/commit/03b99ee87396e41c6bc5d758ae6bad8f0c5d4c33))
+
+
+### Code Refactoring
+
+* rebrand Mailrify to MailGlyph ([431caad](https://github.com/MailGlyph/mailglyph-python/commit/431caadd0eedeed19e77c01ec453005bafe2d9dd))
+
+## [1.0.1](https://github.com/MailGlyph/mailglyph-python/compare/v1.0.0...v1.0.1) (2026-02-16)
+
+
+### Documentation
+
+* Add CI, Release Please, and PyPI publish badges to the README. ([a02f30b](https://github.com/MailGlyph/mailglyph-python/commit/a02f30b6b5ece8a2c52534794ef1a1ed9304ac8a))
+
+## [1.0.0](https://github.com/MailGlyph/mailglyph-python/compare/v0.0.4...v1.0.0) (2026-02-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* complete API redesign, not compatible with 0.1.x
+
+### Features
+
+* initial SDK implementation ([b067d32](https://github.com/MailGlyph/mailglyph-python/commit/b067d3288a77cfc120683bc8a34adb0c0f8dbe4d))
+
+
+### Bug Fixes
+
+* support pydantic type evaluation on python 3.9 ([9237800](https://github.com/MailGlyph/mailglyph-python/commit/9237800485f326acbe03d682f64ccc41883ccb4d))
+
+## Changelog
+
+All notable changes to this project will be documented in this file.

mailglyph-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) MailGlyph
+
+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.

mailglyph-2.0.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: mailglyph
+Version: 2.0.0
+Summary: Official MailGlyph Python SDK
+Project-URL: Homepage, https://github.com/MailGlyph/mailglyph-python
+Project-URL: Repository, https://github.com/MailGlyph/mailglyph-python
+Project-URL: Issues, https://github.com/MailGlyph/mailglyph-python/issues
+Author: MailGlyph
+License: MIT
+License-File: LICENSE
+Keywords: email,mailglyph,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: eval-type-backport>=0.2.0; python_version < '3.10'
+Requires-Dist: httpx>=0.25
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MailGlyph Python SDK
+
+[![CI](https://github.com/MailGlyph/mailglyph-python/actions/workflows/ci.yml/badge.svg)](https://github.com/MailGlyph/mailglyph-python/actions/workflows/ci.yml)
+[![Release Please](https://github.com/MailGlyph/mailglyph-python/actions/workflows/release-please.yml/badge.svg)](https://github.com/MailGlyph/mailglyph-python/actions/workflows/release-please.yml)
+[![Publish to PyPI](https://github.com/MailGlyph/mailglyph-python/actions/workflows/publish.yml/badge.svg)](https://github.com/MailGlyph/mailglyph-python/actions/workflows/publish.yml)
+
+Official Python SDK for the MailGlyph API.
+
+## Installation
+
+```bash
+pip install mailglyph
+```
+
+## Quick Start (Sync)
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph("sk_your_api_key")
+```
+
+## Quick Start (Async)
+
+```python
+from mailglyph import AsyncMailGlyph
+
+client = AsyncMailGlyph("sk_your_api_key")
+```
+
+## Emails
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph("sk_your_api_key")
+
+result = client.emails.send(
+    to="user@example.com",
+    from_={"name": "My App", "email": "hello@myapp.com"},
+    subject="Welcome!",
+    body="<h1>Hello {{name}}</h1>",
+    text="Hello {{name}}",
+    data={"name": "John"},
+)
+
+# Omit `text` to let MailGlyph auto-generate plain text from HTML `body`.
+html_only_result = client.emails.send(
+    to="user@example.com",
+    from_="hello@myapp.com",
+    subject="HTML Only",
+    body="<h1>Hello</h1><p>This will get text/plain fallback.</p>",
+)
+
+# Set text="" to opt out of text/plain generation.
+opt_out_result = client.emails.send(
+    to="user@example.com",
+    from_="hello@myapp.com",
+    subject="No Plain Text Part",
+    body="<h1>Hello</h1>",
+    text="",
+)
+
+verification = client.emails.verify("user@example.com")
+print(verification.valid, verification.is_random_input)
+```
+
+## Events
+
+```python
+from mailglyph import MailGlyph
+
+tracker = MailGlyph("pk_your_public_key")
+tracker.events.track(
+    email="user@example.com",
+    event="purchase",
+    data={"product": "Premium", "amount": 99},
+)
+
+client = MailGlyph("sk_your_api_key")
+names = client.events.get_names()
+```
+
+## Contacts
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph("sk_your_api_key")
+
+contacts = client.contacts.list(limit=50)
+contact = client.contacts.create(email="new@example.com", data={"plan": "premium"})
+client.contacts.update(contact.id, subscribed=False)
+client.contacts.delete(contact.id)
+count = client.contacts.count()
+```
+
+## Segments
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph("sk_your_api_key")
+
+segment = client.segments.create(
+    name="Premium Users",
+    condition={
+        "logic": "AND",
+        "groups": [
+            {
+                "filters": [
+                    {"field": "data.plan", "operator": "equals", "value": "premium"}
+                ]
+            }
+        ],
+    },
+    track_membership=True,
+)
+members = client.segments.list_contacts(segment.id, page=1)
+added = client.segments.add_members(segment.id, emails=["alice@example.com", "bob@example.com"])
+removed = client.segments.remove_members(segment.id, emails=["bob@example.com"])
+```
+
+## Campaigns
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph("sk_your_api_key")
+
+campaign = client.campaigns.create(
+    name="Product Launch",
+    subject="Introducing our new feature!",
+    body="<h1>Big news!</h1><p>Check out our latest feature.</p>",
+    from_email="hello@myapp.com",
+    audience_type="ALL",
+)
+
+campaigns_page = client.campaigns.list(page=1, page_size=20, status="DRAFT")
+client.campaigns.send(campaign.id, scheduled_for="2026-03-01T10:00:00Z")
+client.campaigns.test(campaign.id, email="preview@myapp.com")
+stats = client.campaigns.stats(campaign.id)
+client.campaigns.cancel(campaign.id)
+```
+
+## Async Example
+
+```python
+import asyncio
+
+from mailglyph import AsyncMailGlyph
+
+
+async def main() -> None:
+    async with AsyncMailGlyph("sk_your_api_key") as client:
+        verification = await client.emails.verify("user@example.com")
+        print(verification.valid)
+
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph(
+    "sk_your_api_key",
+    base_url="https://api.mailglyph.com",
+    timeout=30.0,
+    max_retries=3,
+)
+```
+
+## Development
+
+```bash
+pip install -e .[dev]
+ruff check .
+mypy src/
+pytest
+hatch build
+```

mailglyph-2.0.0/README.md

@@ -0,0 +1,184 @@
+# MailGlyph Python SDK
+
+[![CI](https://github.com/MailGlyph/mailglyph-python/actions/workflows/ci.yml/badge.svg)](https://github.com/MailGlyph/mailglyph-python/actions/workflows/ci.yml)
+[![Release Please](https://github.com/MailGlyph/mailglyph-python/actions/workflows/release-please.yml/badge.svg)](https://github.com/MailGlyph/mailglyph-python/actions/workflows/release-please.yml)
+[![Publish to PyPI](https://github.com/MailGlyph/mailglyph-python/actions/workflows/publish.yml/badge.svg)](https://github.com/MailGlyph/mailglyph-python/actions/workflows/publish.yml)
+
+Official Python SDK for the MailGlyph API.
+
+## Installation
+
+```bash
+pip install mailglyph
+```
+
+## Quick Start (Sync)
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph("sk_your_api_key")
+```
+
+## Quick Start (Async)
+
+```python
+from mailglyph import AsyncMailGlyph
+
+client = AsyncMailGlyph("sk_your_api_key")
+```
+
+## Emails
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph("sk_your_api_key")
+
+result = client.emails.send(
+    to="user@example.com",
+    from_={"name": "My App", "email": "hello@myapp.com"},
+    subject="Welcome!",
+    body="<h1>Hello {{name}}</h1>",
+    text="Hello {{name}}",
+    data={"name": "John"},
+)
+
+# Omit `text` to let MailGlyph auto-generate plain text from HTML `body`.
+html_only_result = client.emails.send(
+    to="user@example.com",
+    from_="hello@myapp.com",
+    subject="HTML Only",
+    body="<h1>Hello</h1><p>This will get text/plain fallback.</p>",
+)
+
+# Set text="" to opt out of text/plain generation.
+opt_out_result = client.emails.send(
+    to="user@example.com",
+    from_="hello@myapp.com",
+    subject="No Plain Text Part",
+    body="<h1>Hello</h1>",
+    text="",
+)
+
+verification = client.emails.verify("user@example.com")
+print(verification.valid, verification.is_random_input)
+```
+
+## Events
+
+```python
+from mailglyph import MailGlyph
+
+tracker = MailGlyph("pk_your_public_key")
+tracker.events.track(
+    email="user@example.com",
+    event="purchase",
+    data={"product": "Premium", "amount": 99},
+)
+
+client = MailGlyph("sk_your_api_key")
+names = client.events.get_names()
+```
+
+## Contacts
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph("sk_your_api_key")
+
+contacts = client.contacts.list(limit=50)
+contact = client.contacts.create(email="new@example.com", data={"plan": "premium"})
+client.contacts.update(contact.id, subscribed=False)
+client.contacts.delete(contact.id)
+count = client.contacts.count()
+```
+
+## Segments
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph("sk_your_api_key")
+
+segment = client.segments.create(
+    name="Premium Users",
+    condition={
+        "logic": "AND",
+        "groups": [
+            {
+                "filters": [
+                    {"field": "data.plan", "operator": "equals", "value": "premium"}
+                ]
+            }
+        ],
+    },
+    track_membership=True,
+)
+members = client.segments.list_contacts(segment.id, page=1)
+added = client.segments.add_members(segment.id, emails=["alice@example.com", "bob@example.com"])
+removed = client.segments.remove_members(segment.id, emails=["bob@example.com"])
+```
+
+## Campaigns
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph("sk_your_api_key")
+
+campaign = client.campaigns.create(
+    name="Product Launch",
+    subject="Introducing our new feature!",
+    body="<h1>Big news!</h1><p>Check out our latest feature.</p>",
+    from_email="hello@myapp.com",
+    audience_type="ALL",
+)
+
+campaigns_page = client.campaigns.list(page=1, page_size=20, status="DRAFT")
+client.campaigns.send(campaign.id, scheduled_for="2026-03-01T10:00:00Z")
+client.campaigns.test(campaign.id, email="preview@myapp.com")
+stats = client.campaigns.stats(campaign.id)
+client.campaigns.cancel(campaign.id)
+```
+
+## Async Example
+
+```python
+import asyncio
+
+from mailglyph import AsyncMailGlyph
+
+
+async def main() -> None:
+    async with AsyncMailGlyph("sk_your_api_key") as client:
+        verification = await client.emails.verify("user@example.com")
+        print(verification.valid)
+
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+from mailglyph import MailGlyph
+
+client = MailGlyph(
+    "sk_your_api_key",
+    base_url="https://api.mailglyph.com",
+    timeout=30.0,
+    max_retries=3,
+)
+```
+
+## Development
+
+```bash
+pip install -e .[dev]
+ruff check .
+mypy src/
+pytest
+hatch build
+```