mailflat 0.7.0__tar.gz → 0.9.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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: mailflat
3
- Version: 0.7.0
3
+ Version: 0.9.0
4
4
  Summary: Official Python SDK for MailFlat — disposable, automation-friendly email inboxes with one-line OTP retrieval.
5
5
  Project-URL: Homepage, https://mailflat.net
6
6
  Project-URL: Documentation, https://mailflat.net
@@ -144,6 +144,30 @@ SDK in tests without a network (e.g. `httpx.MockTransport`).
144
144
  conversation instead, which does not look like a reply.
145
145
  - `.mark_read()` / `.delete()` — act on this message directly.
146
146
 
147
+ ## Async
148
+
149
+ Everything above has an `asyncio` twin. Real async I/O, not a thread wrapper — an agent
150
+ watching a fleet of inboxes runs them on one event loop instead of holding a thread per
151
+ `wait_for_otp`:
152
+
153
+ ```python
154
+ import asyncio
155
+ from mailflat.aio import AsyncMailFlat
156
+
157
+ async def main():
158
+ async with AsyncMailFlat() as mf:
159
+ inboxes = await asyncio.gather(*(mf.create(label=f"user-{i}") for i in range(20)))
160
+ codes = await asyncio.gather(*(i.wait_for_otp(timeout=60) for i in inboxes))
161
+ return codes
162
+
163
+ asyncio.run(main())
164
+ ```
165
+
166
+ `AsyncMailFlat` mirrors `MailFlat` method for method, with the same keyword arguments and
167
+ the same rules — retries, `Retry-After`, error types and timeout wording are shared code,
168
+ not two copies. LangChain agents get `AsyncMailFlatToolkit`, which binds `coroutine=` on
169
+ every tool so `ainvoke` awaits instead of parking a thread.
170
+
147
171
  ## Attachments, cc and bcc
148
172
 
149
173
  ```python
@@ -109,6 +109,30 @@ SDK in tests without a network (e.g. `httpx.MockTransport`).
109
109
  conversation instead, which does not look like a reply.
110
110
  - `.mark_read()` / `.delete()` — act on this message directly.
111
111
 
112
+ ## Async
113
+
114
+ Everything above has an `asyncio` twin. Real async I/O, not a thread wrapper — an agent
115
+ watching a fleet of inboxes runs them on one event loop instead of holding a thread per
116
+ `wait_for_otp`:
117
+
118
+ ```python
119
+ import asyncio
120
+ from mailflat.aio import AsyncMailFlat
121
+
122
+ async def main():
123
+ async with AsyncMailFlat() as mf:
124
+ inboxes = await asyncio.gather(*(mf.create(label=f"user-{i}") for i in range(20)))
125
+ codes = await asyncio.gather(*(i.wait_for_otp(timeout=60) for i in inboxes))
126
+ return codes
127
+
128
+ asyncio.run(main())
129
+ ```
130
+
131
+ `AsyncMailFlat` mirrors `MailFlat` method for method, with the same keyword arguments and
132
+ the same rules — retries, `Retry-After`, error types and timeout wording are shared code,
133
+ not two copies. LangChain agents get `AsyncMailFlatToolkit`, which binds `coroutine=` on
134
+ every tool so `ainvoke` awaits instead of parking a thread.
135
+
112
136
  ## Attachments, cc and bcc
113
137
 
114
138
  ```python
@@ -7,15 +7,24 @@ Connected to:
7
7
  - imported by: user code, mailflat-mcp, mailflat.langchain
8
8
 
9
9
  Key exports:
10
- - `MailFlat` — client
10
+ - `MailFlat` — client · `mailflat.aio.AsyncMailFlat` — the same API over asyncio
11
11
  - `Inbox`, `Message`, `Attachment` — domain types
12
12
  - errors: `MailFlatError`, `AuthenticationError`, `MailFlatPermissionError`,
13
13
  `NotFoundError`, `RateLimitError`, `APIError`, `OTPTimeoutError`,
14
14
  `SendFailedError`, `SendTimeoutError`, `EncryptedInboxError`
15
15
  - `redact_secrets()` — strips secret fields from agent tool output (used by MCP/LangChain)
16
+ - `mailflat.agent_results` — the delivery-status payload every model surface returns
16
17
  """
17
18
  from __future__ import annotations
18
19
 
20
+ from .agent_results import (
21
+ SEND_FAILED_NOTE,
22
+ SEND_QUEUED_NOTE,
23
+ SEND_RESULT_KEYS,
24
+ failed_result,
25
+ queued_result,
26
+ sent_result,
27
+ )
19
28
  from .client import MailFlat
20
29
  from .errors import (
21
30
  APIError,
@@ -36,7 +45,7 @@ from .redact import redact_secrets
36
45
 
37
46
  # The package's ONLY version source — pyproject.toml reads it via [tool.hatch.version].
38
47
  # Releasing = bump this line and nothing else.
39
- __version__ = "0.7.0"
48
+ __version__ = "0.9.0"
40
49
 
41
50
  __all__ = [
42
51
  "MailFlat",
@@ -56,5 +65,11 @@ __all__ = [
56
65
  "SendTimeoutError",
57
66
  "EncryptedInboxError",
58
67
  "redact_secrets",
68
+ "SEND_RESULT_KEYS",
69
+ "SEND_QUEUED_NOTE",
70
+ "SEND_FAILED_NOTE",
71
+ "sent_result",
72
+ "queued_result",
73
+ "failed_result",
59
74
  "__version__",
60
75
  ]
@@ -0,0 +1,95 @@
1
+ """Transport RULES, with no I/O — the one place the sync and async clients must agree.
2
+
3
+ Why this module exists: the SDK has two clients now (`MailFlat`, `AsyncMailFlat`). If each
4
+ carried its own copy of "is this retriable", "how long do I wait", "which exception does a
5
+ 403 become", the two would drift the first time one of them is touched — and the drift
6
+ would be invisible, because both would still pass their own tests.
7
+
8
+ B-055 is the scar: `waitForOtp` existed on both surfaces but only one of them went through
9
+ `guarded()`. A name-by-name comparison said the surfaces matched. Behaviour did not.
10
+
11
+ So the clients differ ONLY in how they wait (`time.sleep` vs `await asyncio.sleep`) and how
12
+ they issue the request. Every decision lives here.
13
+
14
+ Connected to:
15
+ - imports from: mailflat.errors
16
+ - imported by: mailflat.client (sync), mailflat.aio (async)
17
+
18
+ Key exports:
19
+ - `RETRY_STATUSES` / `IDEMPOTENT_METHODS` / `MAX_BACKOFF`
20
+ - `retry_after_seconds(headers)` — `Retry-After` in seconds, or None
21
+ - `should_retry(...)` — the retry decision, POST excluded on purpose
22
+ - `backoff_delay(attempt, retry_after)` — how long to wait before the next attempt
23
+ - `interpret(status_code, data)` — raises the right error, or returns the payload
24
+ """
25
+ from __future__ import annotations
26
+
27
+ from typing import Any, Mapping
28
+
29
+ from .errors import MailFlatError, raise_for_status
30
+
31
+ RETRY_STATUSES = {429, 502, 503, 504}
32
+
33
+ # Only side-effect-free (idempotent) methods are retried. POST is deliberately excluded:
34
+ # if the MTA accepts a /send and the gateway then returns 504, a retry delivers THE SAME
35
+ # MAIL TWICE and the user never finds out. POST stays single-shot until we support
36
+ # Idempotency-Key. (B-058 — the Java SDK still has this bug as B-066.)
37
+ IDEMPOTENT_METHODS = {"GET", "HEAD", "DELETE"}
38
+
39
+ MAX_BACKOFF = 8.0
40
+
41
+
42
+ def retry_after_seconds(headers: Mapping[str, str]) -> float | None:
43
+ """Parse the `Retry-After` header (seconds form). Returns None when absent/unparsable.
44
+
45
+ Coming back after 1s when the server said "wait 12s" both earns another 429 and
46
+ stretches the rate-limit window.
47
+ """
48
+ raw = headers.get("Retry-After") or headers.get("retry-after")
49
+ if not raw:
50
+ return None
51
+ try:
52
+ return max(0.0, float(str(raw).strip()))
53
+ except (TypeError, ValueError):
54
+ # The HTTP-date form is valid but rare; rather than guess, fall back to our backoff.
55
+ return None
56
+
57
+
58
+ def should_retry(status_code: int, method: str, idempotent: bool | None,
59
+ attempt: int, max_retries: int) -> bool:
60
+ """Retry this request? `idempotent=True` overrides the method rule.
61
+
62
+ mark_read/burn are POSTs but repeating them is harmless (same end state). It is never
63
+ passed for send: a repeated send delivers the same mail twice.
64
+ """
65
+ if status_code not in RETRY_STATUSES or attempt >= max_retries:
66
+ return False
67
+ if idempotent is None:
68
+ return method.upper() in IDEMPOTENT_METHODS
69
+ return bool(idempotent)
70
+
71
+
72
+ def backoff_delay(attempt: int, retry_after: float | None) -> float:
73
+ """Seconds to wait before attempt N. The server's `Retry-After` wins when it sent one."""
74
+ delay = retry_after if retry_after is not None else min(2 ** attempt * 0.5, MAX_BACKOFF)
75
+ return min(delay, MAX_BACKOFF)
76
+
77
+
78
+ def error_detail(data: Any) -> str:
79
+ """Pull the human-readable reason out of an error body."""
80
+ if isinstance(data, dict):
81
+ return data.get("detail") or data.get("error") or ""
82
+ return ""
83
+
84
+
85
+ def interpret(status_code: int, data: Any, *, retry_after: float | None = None) -> dict:
86
+ """Turn a finished response into a payload — or the right exception.
87
+
88
+ The `2xx + {"error": ...}` branch is a safety net, not theory: an endpoint that answers
89
+ 200 with an error body would otherwise look like success to every caller.
90
+ """
91
+ if status_code >= 400:
92
+ raise_for_status(status_code, error_detail(data), retry_after=retry_after)
93
+ if isinstance(data, dict) and data.get("error"):
94
+ raise MailFlatError(data["error"], status_code=status_code)
95
+ return data if isinstance(data, dict) else {}
@@ -0,0 +1,94 @@
1
+ """The shape a MODEL sees when it asks "did my mail actually go out?".
2
+
3
+ `send()` is asynchronous (the endpoint answers 202 Accepted), so every model surface needs
4
+ a way to ask about delivery afterwards. Code surfaces raise exceptions for that; a model
5
+ surface hands the model a dictionary and the model decides what to do next. Those
6
+ dictionaries are built HERE, once, so the MCP server and both LangChain toolkits cannot
7
+ drift apart — the same reason `should_retry`/`backoff_delay` live in `_http.py`.
8
+
9
+ ⚠️ The dangerous branch is the TIMEOUT, not the failure. A timeout means "still queued,
10
+ the queue is still retrying" — it does NOT mean the mail was lost. A model that reads a
11
+ timeout as failure will send the mail a second time, so the payload says `delivered: false`
12
+ without ever saying "failed", and states outright that resending is wrong.
13
+
14
+ Connected to:
15
+ - imports from: mailflat.redact
16
+ - imported by: mailflat.langchain (both toolkits), mailflat_mcp.server
17
+
18
+ Key exports:
19
+ - `SEND_RESULT_KEYS` — the keys every surface must return (cross-surface parity lock)
20
+ - `SEND_QUEUED_NOTE` / `SEND_FAILED_NOTE` — the sentences the model reads
21
+ - `sent_result()`, `queued_result()`, `failed_result()` — the three outcomes
22
+ """
23
+ from __future__ import annotations
24
+
25
+ from typing import Any
26
+
27
+ from .redact import redact_secrets
28
+
29
+ #: Every `wait_until_sent` result carries exactly these keys, on every surface. A model
30
+ #: that learned to read one surface can read the others; a test compares this tuple with
31
+ #: what the TypeScript surface returns.
32
+ SEND_RESULT_KEYS = ("status", "delivered", "timed_out", "message", "note")
33
+
34
+ #: Shown when the mail is still queued. The last sentence is the point of the whole module.
35
+ #:
36
+ #: Written WITHOUT the word "fail" on purpose, and locked that way by test. The first draft
37
+ #: opened with "This is NOT a failure" — accurate, but it puts the very word we are trying
38
+ #: to keep out of the model's head into the payload, and negations are the first thing a
39
+ #: model skims past. Saying what is true ("still on its way") beats denying what is false.
40
+ SEND_QUEUED_NOTE = (
41
+ "Still queued when the timeout elapsed. The queue keeps retrying with backoff, so this "
42
+ "mail is still on its way. Do NOT send it again — a duplicate would reach the recipient "
43
+ "twice. Ask again later, or subscribe to the message.delivered webhook."
44
+ )
45
+
46
+ #: Shown when the queue gave up. Here resending after fixing the cause IS the right move.
47
+ SEND_FAILED_NOTE = (
48
+ "Delivery permanently failed and the queue will not retry. Read `error` for the "
49
+ "reason (a rejection from the recipient's mail server, an unknown mailbox, and so on). "
50
+ "Fix the cause before sending again."
51
+ )
52
+
53
+
54
+ def sent_result(message: Any) -> dict[str, Any]:
55
+ """The mail reached a final, successful state.
56
+
57
+ `unsigned` counts as delivered: it means the mail went out without a DKIM signature,
58
+ not that it stayed behind. Reporting it as undelivered would make an agent resend a
59
+ mail the recipient already has.
60
+ """
61
+ return redact_secrets({
62
+ "status": message.send_status,
63
+ "delivered": True,
64
+ "timed_out": False,
65
+ "message": message.raw,
66
+ "note": "",
67
+ })
68
+
69
+
70
+ def queued_result(error: Any) -> dict[str, Any]:
71
+ """We stopped waiting; the queue did not. Built from a `SendTimeoutError`."""
72
+ return {
73
+ "status": error.status or "queued",
74
+ "delivered": False,
75
+ "timed_out": True,
76
+ "message": None,
77
+ "note": SEND_QUEUED_NOTE,
78
+ }
79
+
80
+
81
+ def failed_result(error: Any) -> dict[str, Any]:
82
+ """Delivery is over and it did not work. Built from a `SendFailedError`.
83
+
84
+ Carries an extra `error` key on top of `SEND_RESULT_KEYS`: the reason is the only
85
+ thing that lets the caller decide whether a corrected resend makes sense.
86
+ """
87
+ return {
88
+ "status": error.status or "failed",
89
+ "delivered": False,
90
+ "timed_out": False,
91
+ "message": None,
92
+ "note": SEND_FAILED_NOTE,
93
+ "error": str(error),
94
+ }