ashemail-sdk 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,18 @@
1
+ Proprietary License
2
+
3
+ Copyright (c) 2026 Ashemail. All rights reserved.
4
+
5
+ This software, including its source code and accompanying documentation,
6
+ is the proprietary property of Ashemail. It is licensed, not sold.
7
+
8
+ You may not copy, modify, distribute, sublicense, or otherwise use this
9
+ software except as expressly permitted by a written agreement with
10
+ Ashemail. No part of this software may be reproduced or transmitted in
11
+ any form or by any means without prior written permission from Ashemail.
12
+
13
+ This software is provided "as is", without warranty of any kind, express
14
+ or implied, including but not limited to the warranties of merchantability,
15
+ fitness for a particular purpose, and non-infringement. In no event shall
16
+ Ashemail be liable for any claim, damages, or other liability, whether in
17
+ an action of contract, tort, or otherwise, arising from, out of, or in
18
+ connection with this software or the use or other dealings in this software.
@@ -0,0 +1,97 @@
1
+ Metadata-Version: 2.4
2
+ Name: ashemail-sdk
3
+ Version: 1.0.0
4
+ Summary: Official Python SDK for the Ashemail Public API v1. Types are generated from docs/openapi/openapi.json; never hand-edit generated_types.py.
5
+ License-Expression: LicenseRef-Proprietary
6
+ Project-URL: Homepage, https://app.ashemail.com
7
+ Project-URL: Source, https://github.com/Farhadali007/ashemail
8
+ Requires-Python: >=3.11
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ Dynamic: license-file
12
+
13
+ # ashemail-sdk
14
+
15
+ Official Python SDK for the Ashemail Public API v1. Same resource
16
+ semantics as the TypeScript SDK (`@ashemail/sdk`): same methods, same
17
+ auth story, same retry and idempotency rules, same error shape, same
18
+ fixture suite.
19
+
20
+ ## Status
21
+
22
+ Verified artifact, not yet published. Releases publish to PyPI through
23
+ GitHub Actions trusted publishing (OIDC) — no long-lived PyPI token is
24
+ stored anywhere; a version tag (`sdk-py-v*`) plus owner approval of
25
+ the `pypi-publish` environment are still required. Until the first
26
+ release, use it from this repository
27
+ (`packages/ashemail-sdk-python`). Nothing about publication is claimed
28
+ or faked.
29
+
30
+ ## Install (once published)
31
+
32
+ ```sh
33
+ pip install ashemail-sdk
34
+ ```
35
+
36
+ Requires Python 3.11 or later. Standard library only: no third-party
37
+ dependencies. This is a sync client; an async client is deliberately
38
+ not shipped (one client, done well).
39
+
40
+ ## Quickstart
41
+
42
+ ```python
43
+ import os
44
+ from ashemail_sdk import AshemailClient
45
+
46
+ client = AshemailClient(api_key=os.environ["ASHEMAIL_API_KEY"])
47
+ accepted = client.send_message(
48
+ {"from": "news@example.test", "to": ["a@example.test"], "subject": "Hi", "text": "Hello"},
49
+ idempotency_key="welcome-0001",
50
+ )
51
+ print(accepted["id"], accepted["status"])
52
+ status = client.get_message(accepted["id"])
53
+ print(status["status"], status["stream"])
54
+ ```
55
+
56
+ ## Auth
57
+
58
+ - `api_key`: an API key or Service Account credential (same form).
59
+ Used for sending, credential message logs, conversion events, usage.
60
+ - `session_token`: a dashboard session token. Required for the
61
+ session-managed surfaces (credentials, domains, suppressions,
62
+ webhooks, Service Accounts, organization message logs). Calling one
63
+ without a session token raises `AshemailError` with code
64
+ `missing_session_token` before any request is sent.
65
+
66
+ Usage (`get_usage`) and Service Account methods are part of the v1 API.
67
+
68
+ ## Behaviour
69
+
70
+ - Errors are `AshemailError` with `status`, `code`, `request_id`
71
+ (the `x-correlation-id` header, falling back to the body's
72
+ `traceId`), and `field_errors` for validation failures.
73
+ - Retries: only GETs and idempotent sends (POST `/v1/messages` with
74
+ an idempotency key), on 429/502/503/504 and network failures,
75
+ exponential backoff, 3 retries by default. Rotates, revocations,
76
+ and credential creation are never auto-retried.
77
+ - Pagination: `search_messages` returns a cursor page
78
+ (`{"items": ..., "nextCursor": ...}`); `search_all_messages` is a
79
+ generator over every page.
80
+ - Webhooks: `verify_webhook_signature(secret=..., raw_body=...,
81
+ signature_header=...)` checks the `ashemail-signature` header
82
+ (HMAC-SHA256 over `timestamp + "." + raw body`, any matching v1
83
+ accepted, 300s tolerance by default).
84
+ - For tests, pass a `transport` callable; the fixture suite in
85
+ `tests/test_fixtures.py` reads the same
86
+ `packages/fixtures/sdk-fixtures.json` as the TypeScript suite.
87
+
88
+ ## Types
89
+
90
+ `generated_types.py` is generated from `docs/openapi/openapi.json`
91
+ by `node scripts/openapi/generate-sdk-types.mjs`. Never hand-edit it:
92
+ fix the contract, regenerate. Anonymous nested objects become
93
+ `dict[str, Any]`; named components become TypedDicts. The full guide
94
+ (auth, errors, pagination, idempotency, retries, environments,
95
+ webhook verification) is in `docs/developer/api-guide.md`, and the
96
+ contract itself is served at `GET /v1/openapi.json` and in the
97
+ dashboard at Developer > API Reference.
@@ -0,0 +1,85 @@
1
+ # ashemail-sdk
2
+
3
+ Official Python SDK for the Ashemail Public API v1. Same resource
4
+ semantics as the TypeScript SDK (`@ashemail/sdk`): same methods, same
5
+ auth story, same retry and idempotency rules, same error shape, same
6
+ fixture suite.
7
+
8
+ ## Status
9
+
10
+ Verified artifact, not yet published. Releases publish to PyPI through
11
+ GitHub Actions trusted publishing (OIDC) — no long-lived PyPI token is
12
+ stored anywhere; a version tag (`sdk-py-v*`) plus owner approval of
13
+ the `pypi-publish` environment are still required. Until the first
14
+ release, use it from this repository
15
+ (`packages/ashemail-sdk-python`). Nothing about publication is claimed
16
+ or faked.
17
+
18
+ ## Install (once published)
19
+
20
+ ```sh
21
+ pip install ashemail-sdk
22
+ ```
23
+
24
+ Requires Python 3.11 or later. Standard library only: no third-party
25
+ dependencies. This is a sync client; an async client is deliberately
26
+ not shipped (one client, done well).
27
+
28
+ ## Quickstart
29
+
30
+ ```python
31
+ import os
32
+ from ashemail_sdk import AshemailClient
33
+
34
+ client = AshemailClient(api_key=os.environ["ASHEMAIL_API_KEY"])
35
+ accepted = client.send_message(
36
+ {"from": "news@example.test", "to": ["a@example.test"], "subject": "Hi", "text": "Hello"},
37
+ idempotency_key="welcome-0001",
38
+ )
39
+ print(accepted["id"], accepted["status"])
40
+ status = client.get_message(accepted["id"])
41
+ print(status["status"], status["stream"])
42
+ ```
43
+
44
+ ## Auth
45
+
46
+ - `api_key`: an API key or Service Account credential (same form).
47
+ Used for sending, credential message logs, conversion events, usage.
48
+ - `session_token`: a dashboard session token. Required for the
49
+ session-managed surfaces (credentials, domains, suppressions,
50
+ webhooks, Service Accounts, organization message logs). Calling one
51
+ without a session token raises `AshemailError` with code
52
+ `missing_session_token` before any request is sent.
53
+
54
+ Usage (`get_usage`) and Service Account methods are part of the v1 API.
55
+
56
+ ## Behaviour
57
+
58
+ - Errors are `AshemailError` with `status`, `code`, `request_id`
59
+ (the `x-correlation-id` header, falling back to the body's
60
+ `traceId`), and `field_errors` for validation failures.
61
+ - Retries: only GETs and idempotent sends (POST `/v1/messages` with
62
+ an idempotency key), on 429/502/503/504 and network failures,
63
+ exponential backoff, 3 retries by default. Rotates, revocations,
64
+ and credential creation are never auto-retried.
65
+ - Pagination: `search_messages` returns a cursor page
66
+ (`{"items": ..., "nextCursor": ...}`); `search_all_messages` is a
67
+ generator over every page.
68
+ - Webhooks: `verify_webhook_signature(secret=..., raw_body=...,
69
+ signature_header=...)` checks the `ashemail-signature` header
70
+ (HMAC-SHA256 over `timestamp + "." + raw body`, any matching v1
71
+ accepted, 300s tolerance by default).
72
+ - For tests, pass a `transport` callable; the fixture suite in
73
+ `tests/test_fixtures.py` reads the same
74
+ `packages/fixtures/sdk-fixtures.json` as the TypeScript suite.
75
+
76
+ ## Types
77
+
78
+ `generated_types.py` is generated from `docs/openapi/openapi.json`
79
+ by `node scripts/openapi/generate-sdk-types.mjs`. Never hand-edit it:
80
+ fix the contract, regenerate. Anonymous nested objects become
81
+ `dict[str, Any]`; named components become TypedDicts. The full guide
82
+ (auth, errors, pagination, idempotency, retries, environments,
83
+ webhook verification) is in `docs/developer/api-guide.md`, and the
84
+ contract itself is served at `GET /v1/openapi.json` and in the
85
+ dashboard at Developer > API Reference.
@@ -0,0 +1,19 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "ashemail-sdk"
7
+ version = "1.0.0"
8
+ description = "Official Python SDK for the Ashemail Public API v1. Types are generated from docs/openapi/openapi.json; never hand-edit generated_types.py."
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "LicenseRef-Proprietary"
12
+ dependencies = []
13
+
14
+ [project.urls]
15
+ Homepage = "https://app.ashemail.com"
16
+ Source = "https://github.com/Farhadali007/ashemail"
17
+
18
+ [tool.setuptools.packages.find]
19
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,6 @@
1
+ """Official Python SDK for the Ashemail Public API v1."""
2
+
3
+ from .client import AshemailClient, AshemailError, FieldError, verify_webhook_signature
4
+
5
+ __all__ = ["AshemailClient", "AshemailError", "FieldError", "verify_webhook_signature"]
6
+ __version__ = "1.0.0"