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.
- {mailflat-0.7.0 → mailflat-0.9.0}/PKG-INFO +25 -1
- {mailflat-0.7.0 → mailflat-0.9.0}/README.md +24 -0
- {mailflat-0.7.0 → mailflat-0.9.0}/src/mailflat/__init__.py +17 -2
- mailflat-0.9.0/src/mailflat/_http.py +95 -0
- mailflat-0.9.0/src/mailflat/agent_results.py +94 -0
- mailflat-0.9.0/src/mailflat/aio.py +379 -0
- {mailflat-0.7.0 → mailflat-0.9.0}/src/mailflat/client.py +14 -51
- {mailflat-0.7.0 → mailflat-0.9.0}/src/mailflat/inbox.py +26 -17
- mailflat-0.9.0/src/mailflat/langchain.py +587 -0
- mailflat-0.7.0/src/mailflat/langchain.py +0 -254
- {mailflat-0.7.0 → mailflat-0.9.0}/.gitignore +0 -0
- {mailflat-0.7.0 → mailflat-0.9.0}/LICENSE +0 -0
- {mailflat-0.7.0 → mailflat-0.9.0}/pyproject.toml +0 -0
- {mailflat-0.7.0 → mailflat-0.9.0}/src/mailflat/errors.py +0 -0
- {mailflat-0.7.0 → mailflat-0.9.0}/src/mailflat/py.typed +0 -0
- {mailflat-0.7.0 → mailflat-0.9.0}/src/mailflat/redact.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: mailflat
|
|
3
|
-
Version: 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.
|
|
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
|
+
}
|