forktex-mail 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.
Files changed (50) hide show
  1. forktex_mail-1.0.0/AGENTS.md +18 -0
  2. forktex_mail-1.0.0/CHANGELOG.md +32 -0
  3. forktex_mail-1.0.0/LICENSE +45 -0
  4. forktex_mail-1.0.0/NOTICE +18 -0
  5. forktex_mail-1.0.0/PKG-INFO +133 -0
  6. forktex_mail-1.0.0/README.md +101 -0
  7. forktex_mail-1.0.0/SECURITY.md +47 -0
  8. forktex_mail-1.0.0/docs/assets/mail-banner.png +0 -0
  9. forktex_mail-1.0.0/docs/development.md +265 -0
  10. forktex_mail-1.0.0/docs/guide.md +587 -0
  11. forktex_mail-1.0.0/docs/operating.md +179 -0
  12. forktex_mail-1.0.0/docs/reference.md +332 -0
  13. forktex_mail-1.0.0/fsd.toml +67 -0
  14. forktex_mail-1.0.0/poetry.lock +3911 -0
  15. forktex_mail-1.0.0/poetry.toml +25 -0
  16. forktex_mail-1.0.0/pyproject.toml +138 -0
  17. forktex_mail-1.0.0/scripts/clean.py +60 -0
  18. forktex_mail-1.0.0/scripts/license_headers.py +103 -0
  19. forktex_mail-1.0.0/scripts/oldest.py +66 -0
  20. forktex_mail-1.0.0/scripts/release_check.py +150 -0
  21. forktex_mail-1.0.0/scripts/smoke.py +64 -0
  22. forktex_mail-1.0.0/src/forktex_mail/__init__.py +87 -0
  23. forktex_mail-1.0.0/src/forktex_mail/errors.py +239 -0
  24. forktex_mail-1.0.0/src/forktex_mail/imap.py +673 -0
  25. forktex_mail-1.0.0/src/forktex_mail/mailbox.py +254 -0
  26. forktex_mail-1.0.0/src/forktex_mail/message.py +410 -0
  27. forktex_mail-1.0.0/src/forktex_mail/py.typed +0 -0
  28. forktex_mail-1.0.0/src/forktex_mail/ratelimit.py +125 -0
  29. forktex_mail-1.0.0/src/forktex_mail/smtp.py +409 -0
  30. forktex_mail-1.0.0/src/forktex_mail/testing.py +94 -0
  31. forktex_mail-1.0.0/tests/__init__.py +23 -0
  32. forktex_mail-1.0.0/tests/_containers.py +181 -0
  33. forktex_mail-1.0.0/tests/conftest.py +56 -0
  34. forktex_mail-1.0.0/tests/contract/__init__.py +23 -0
  35. forktex_mail-1.0.0/tests/contract/test_classification.py +922 -0
  36. forktex_mail-1.0.0/tests/contract/test_json.py +168 -0
  37. forktex_mail-1.0.0/tests/contract/test_mailbox.py +256 -0
  38. forktex_mail-1.0.0/tests/contract/test_message.py +472 -0
  39. forktex_mail-1.0.0/tests/contract/test_public_surface.py +112 -0
  40. forktex_mail-1.0.0/tests/contract/test_ratelimit.py +146 -0
  41. forktex_mail-1.0.0/tests/contract/test_reading.py +143 -0
  42. forktex_mail-1.0.0/tests/contract/test_sending.py +273 -0
  43. forktex_mail-1.0.0/tests/scripted.py +384 -0
  44. forktex_mail-1.0.0/tests/usage/__init__.py +23 -0
  45. forktex_mail-1.0.0/tests/usage/test_bounces.py +48 -0
  46. forktex_mail-1.0.0/tests/usage/test_connection_settings.py +90 -0
  47. forktex_mail-1.0.0/tests/usage/test_process_an_inbox.py +101 -0
  48. forktex_mail-1.0.0/tests/usage/test_sending_and_receiving.py +295 -0
  49. forktex_mail-1.0.0/tests/usage/test_sending_from_an_api.py +46 -0
  50. forktex_mail-1.0.0/tests/usage/test_testing_code_that_sends.py +121 -0
@@ -0,0 +1,18 @@
1
+ # AGENTS.md
2
+
3
+ `forktex-mail` is a library: send mail over SMTP and read, file and process
4
+ mailboxes over IMAP, from any Python process, over the `forktex` substrate. It
5
+ has no CLI and no service of its own, and no provider, host or company appears
6
+ in it.
7
+
8
+ For consumers: [`README.md`](README.md), then [`docs/guide.md`](docs/guide.md),
9
+ [`docs/reference.md`](docs/reference.md) and [`docs/operating.md`](docs/operating.md).
10
+
11
+ For working on the library: [`docs/development.md`](docs/development.md) — the
12
+ layout, the conventions (classification from protocol codes only, no
13
+ connection outliving its call), the design decisions and what proves what. Read
14
+ it before changing anything.
15
+
16
+ The gate is `fsd assurance`, `fsd security` and `fsd documentation`, bound in
17
+ [`fsd.toml`](fsd.toml); the tests need Docker. Publishing is manual: a person
18
+ runs `fsd tag`, then `fsd publish`.
@@ -0,0 +1,32 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [1.0.0] - 2026-11-19
10
+
11
+ The first stable version: send and receive mail from any Python process, every failure classified by who has to act.
12
+
13
+ ### Added
14
+
15
+ - `Mailbox`: one account's settings — SMTP and IMAP hosts and ports, login, sender, Reply-To, `security` (`auto`, `ssl`, `starttls`, `none`) for SMTP and `imap_security` (`auto`, `ssl`, `starttls`) for IMAP, each on its own, `helo` (a host name or a bracketed address literal), `ca_pem` (refused on construction unless it loads at least one certificate), `verify_tls`, `timeout` for connecting and each command's reply (the go-ahead after `DATA` waits at least 120 seconds, as RFC 5321 asks), `data_timeout` (600 seconds) for each 64 KiB block of a message's body and for the answer to it; `replace`, `redacted` (each protocol's security included), `from_address`, `has_credentials`. Give the password or `oauth2_token` as text or a `SecretStr`; read it back as a `SecretStr`. `security="none"` refuses credentials over SMTP; IMAP always uses TLS. `Security` and `ImapSecurity` name the settings' types.
16
+ - `compose`: text, HTML or both; recipients as `Address` values or `"Name <address>"` strings; Reply-To; attachments; `in_reply_to` and `references`; a fixed `message_id`; extra `headers` such as `List-Unsubscribe`.
17
+ - `Transport`, a typing protocol of `send`, `aclose` and `async with`, for annotations (not runtime-checkable); implement all of them in a transport of your own.
18
+ - `Smtp`: one connection per message, or a session with `async with`; close a session you hold yourself with `aclose()`. Closing sends the messages already waiting; one sent after closing began raises `invalid`, while one still waiting on a rate limit is sent on a connection of its own. Cancelling the close still ends the session and closes its connection. Cancelling a `send` mid-transaction drops its connection at once, never says QUIT into it and never reuses it. `send` is the one-shot form, `probe` checks a sign-in without sending.
19
+ - Signing in is one attempt with one mechanism the server offers. SMTP: XOAUTH2 for a token; PLAIN, else LOGIN, for a password. IMAP: XOAUTH2 for a token under `AUTH=XOAUTH2`; LOGIN for a password unless the server advertises `LOGINDISABLED` or the sign-in is not ASCII, else `AUTHENTICATE PLAIN` under `AUTH=PLAIN`. With no usable mechanism, `config`, and no credential is sent.
20
+ - `tls` is a failure while connecting or during STARTTLS; a TLS-layer error that drops an established connection is a lost connection (`unreachable`, or `unknown` after the final `.`).
21
+ - A failure while a message's body is sent, or a body that stalls for `data_timeout`, is `unreachable`, and its final `.` is never sent; after the final `.`, a lost connection, a timeout or an answer outside the protocol is `unknown`.
22
+ - A message larger than the server's SIZE, as it will go on the wire, is refused before upload; a refusal for size at any step is `invalid`. A `552` refusal of a recipient is transient.
23
+ - `Sent`, with each refused recipient as a `Refusal`, and the server's answer in `Sent.response` — on Amazon SES, the Message-ID it assigned.
24
+ - `RateLimit` and `acquire`: share the same limits between every sender in a process; `seed` them after a restart.
25
+ - `fetch`, `folders`, `archive`, `mark`, `move`, `delete`: read a folder of any size read-only from `after_uid` — with `limit`, the oldest messages after it, else the newest (all of them when fewer match); an IMAP reply line too long to read is `rejected`, never called a server refusal; file sent mail; change messages by UID with the `uid_validity` they were read under, any number of them, in commands of at most about 8 000 octets. Give a folder as a name, or as a path tuple to land in the server's personal namespace.
26
+ - `messages`: read a whole folder oldest first, a batch at a time, with its `uid_validity` to resume from. `Messages` is the type it returns, with read-only `folder` and `uid_validity`.
27
+ - `parse` and `Received`: never raises; what could not be read is in `defects`. A UID or UIDVALIDITY the server never gave is `None`. Reply with `in_reply_to=received.message_id`: it is always a bare `<id>` or empty. Thread ids are printable ASCII; `compose` refuses any other.
28
+ - `Received.bounce`: RFC 3464 delivery reports; match `bounce.original_message_id` against `Sent.message_id`.
29
+ - `MailError`, a `forktex.error.AppError`, with `kind` — `invalid`, `config`, `auth`, `tls`, `unreachable`, `deferred`, `rejected`, `unknown` — `reply`, `enhanced` and `transient`. Retry only when `transient` is true; on `unknown`, send again with the same Message-ID only where a duplicate is acceptable. Only the transient kinds map to `UNAVAILABLE` and `RATE_LIMITED`; `invalid` is `VALIDATION`, `config`, `auth` and `tls` are `INTERNAL`, `rejected` and `unknown` are `FAILED`. No message quotes the server or a folder name.
30
+ - `Capture`, a `Transport` for tests that captures messages, read back as a tuple from `sent`, and fails or refuses on cue.
31
+ - JSON: every value writes camelCase keys and reads either spelling; `Sent.accepted`, `Refusal.transient`, `MailFolder.selectable` and `BouncedRecipient.permanent` are written too. `Attachment.data` is standard base64 (RFC 4648, section 4), read back in either alphabet; an absent value is `null`.
32
+ - Requires forktex 1.2 or a later 1.x, pydantic 2.14 or a later 2.x, email-validator 2.2 or a later 2.x, and aiosmtplib 5.1.3 or a later 5.1 release.
@@ -0,0 +1,45 @@
1
+ ForkTex Mail -- Dual License
2
+
3
+ Copyright (C) 2026 FORKTEX S.R.L.
4
+
5
+ This software is licensed under a dual-license model:
6
+
7
+ ============================================================================
8
+
9
+ 1. OPEN-SOURCE LICENSE -- GNU Affero General Public License v3.0 (AGPL-3.0)
10
+
11
+ You may use, modify, and redistribute this software under the terms of the
12
+ GNU Affero General Public License v3.0 or later, as published by the Free
13
+ Software Foundation. The full license text is available at:
14
+ https://www.gnu.org/licenses/agpl-3.0.html
15
+
16
+ Key obligations under AGPL-3.0:
17
+ - Any modified version MUST be released under the same AGPL-3.0 license.
18
+ - If you run a modified version on a server and let users interact with it
19
+ over a network, you MUST make the complete source code available to those
20
+ users under AGPL-3.0.
21
+ - You MUST preserve all copyright notices and attribution to FORKTEX S.R.L.
22
+
23
+ ============================================================================
24
+
25
+ 2. COMMERCIAL LICENSE
26
+
27
+ If you wish to use this software without the obligations of AGPL-3.0 --
28
+ for example, to keep your modifications proprietary, to embed this software
29
+ in a closed-source product, or to operate it as part of a commercial service
30
+ without releasing your source code -- you MUST obtain a commercial license
31
+ from FORKTEX S.R.L.
32
+
33
+ Commercial licensing includes, but is not limited to:
34
+ - SaaS / hosted deployments generating revenue
35
+ - Embedding in proprietary products or platforms
36
+ - Redistribution in closed-source form
37
+ - Use by organizations exceeding the AGPL-3.0 compliance scope
38
+
39
+ For commercial licensing inquiries, contact:
40
+ info@forktex.com
41
+
42
+ ============================================================================
43
+
44
+ Unless you have obtained a separate commercial license from FORKTEX S.R.L.,
45
+ your use of this software is governed exclusively by the AGPL-3.0 license.
@@ -0,0 +1,18 @@
1
+ ForkTex Mail
2
+ Copyright (C) 2026 FORKTEX S.R.L.
3
+
4
+ ForkTex Mail is a small library for sending and receiving e-mail from any
5
+ Python process: SMTP to send, IMAP to file and read, errors classified by
6
+ the protocol.
7
+
8
+ This product is dual-licensed:
9
+
10
+ * GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), or
11
+ * A proprietary commercial license from FORKTEX S.R.L.
12
+
13
+ If you cannot meet the obligations of the AGPL -- including its network-use
14
+ source-disclosure requirement -- you MUST obtain a commercial license before
15
+ using this software. Contact info@forktex.com.
16
+
17
+ Third-party components are distributed under their own licenses; see the
18
+ dependency metadata in pyproject.toml.
@@ -0,0 +1,133 @@
1
+ Metadata-Version: 2.4
2
+ Name: forktex-mail
3
+ Version: 1.0.0
4
+ Summary: Send and receive e-mail from any Python process: SMTP to send, IMAP to file and read, errors classified by the protocol.
5
+ License-Expression: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
6
+ License-File: LICENSE
7
+ License-File: NOTICE
8
+ Keywords: email,smtp,imap,mail,async
9
+ Author: FORKTEX
10
+ Author-email: info@forktex.com
11
+ Requires-Python: >=3.14,<4.0
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Framework :: AsyncIO
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Communications :: Email
20
+ Classifier: Typing :: Typed
21
+ Requires-Dist: aiosmtplib (>=5.1.3,<5.2)
22
+ Requires-Dist: email-validator (>=2.2,<3)
23
+ Requires-Dist: forktex (>=1.2,<2)
24
+ Requires-Dist: pydantic (>=2.14,<3)
25
+ Project-URL: Bug Tracker, https://github.com/forktex/forktex-mail/issues
26
+ Project-URL: Changelog, https://github.com/forktex/forktex-mail/blob/master/CHANGELOG.md
27
+ Project-URL: Documentation, https://github.com/forktex/forktex-mail/tree/master/docs
28
+ Project-URL: Homepage, https://forktex.com
29
+ Project-URL: Repository, https://github.com/forktex/forktex-mail
30
+ Description-Content-Type: text/markdown
31
+
32
+ <p align="center">
33
+ <img src="https://raw.githubusercontent.com/forktex/forktex-mail/master/docs/assets/mail-banner.png" alt="forktex-mail" height="120">
34
+ </p>
35
+
36
+ <p align="center">
37
+ <a href="https://pypi.org/project/forktex-mail/"><img src="https://img.shields.io/pypi/v/forktex-mail.svg" alt="PyPI"></a>
38
+ <a href="https://pypi.org/project/forktex-mail/"><img src="https://img.shields.io/pypi/pyversions/forktex-mail.svg" alt="Python"></a>
39
+ <a href="https://github.com/forktex/forktex-mail/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/forktex-mail.svg" alt="License"></a>
40
+ </p>
41
+
42
+ Send and process e-mail from any Python process — a one-off script, a worker or
43
+ a production API. SMTP sends, one connection per message or one session for
44
+ many; IMAP reads a mailbox incrementally, files, marks, moves and deletes. Every
45
+ failure says who has to act and whether to retry, decided from the codes SMTP
46
+ and IMAP define, never from a provider's wording.
47
+
48
+ ```bash
49
+ pip install forktex-mail
50
+ ```
51
+
52
+ ```python
53
+ from forktex_mail import Mailbox, compose, fetch, send
54
+
55
+ box = Mailbox(host="mail.example.com", user="me@example.com", password="…", sender_name="Me")
56
+
57
+ sent = await send(box, compose(box, to="Ana <ana@example.com>", subject="Hello", text="Hi!", html="<p>Hi!</p>"))
58
+ inbox = await fetch(box, unseen=True)
59
+ ```
60
+
61
+ ## Requirements
62
+
63
+ | | |
64
+ |---|---|
65
+ | **Python** | 3.14 |
66
+ | **A mail server** | Any SMTP submission server to send; IMAP to read, file and process. Battle-tested against Zoho Mail, Postfix and Dovecot, and GreenMail. |
67
+ | **Sign-in** | A password (or an app password), or an OAuth2 access token for providers that require one (Microsoft 365, Outlook.com, Gmail). |
68
+ | **TLS** | Implicit TLS or STARTTLS, verified against the system's authorities or a private one you supply. Plain SMTP only for a local catcher, without credentials. |
69
+
70
+ ## What you can build
71
+
72
+ | You want to | Read |
73
+ |---|---|
74
+ | Describe a mailbox once, from settings or a database row | [A mailbox](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#a-mailbox) |
75
+ | Send from a script, an API or a worker | [Send from a script](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#send-from-a-script), [Send from an API](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#send-from-an-api) |
76
+ | Send many messages on one logged-in connection | [Send many messages](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#send-many-messages) |
77
+ | Attach files, thread replies, add `List-Unsubscribe` | [Attachments, threads and headers](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#attachments-threads-and-headers) |
78
+ | Stay under a host's sending caps | [Stay under a sending cap](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#stay-under-a-sending-cap) |
79
+ | Sign in to Microsoft 365, Outlook.com or Gmail with OAuth2 | [Sign in with OAuth2](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#sign-in-with-oauth2) |
80
+ | Read a mailbox, read on from where you stopped, or read a whole folder in batches | [Read a mailbox](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#read-a-mailbox-and-read-on-later) |
81
+ | File sent mail, mark, move and delete — process an inbox | [Process an inbox](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#process-an-inbox) |
82
+ | Find out which messages bounced, and why | [Read bounces](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#read-bounces) |
83
+ | Decide whether to retry, fix settings or drop a message | [Decide what to do with a failure](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#decide-what-to-do-with-a-failure) |
84
+ | Test your own code that sends mail, without a server | [Test code that sends mail](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#test-code-that-sends-mail) |
85
+
86
+ ## How it works
87
+
88
+ | Concept | What it is |
89
+ |---|---|
90
+ | **Mailbox** | One account's settings: hosts, sign-in, sender, TLS. Pure data; never reads the environment. |
91
+ | **Transport** | Anything that sends a message, says what the server did, and closes: `Smtp`, or `Capture` in tests. |
92
+ | **Session** | `async with Smtp(mailbox)`: one login for many messages, checked before each and reconnected when gone. |
93
+ | **Received** | A message read back: who it is `from_` and to, text, HTML, attachments, every header, the server's flags and arrival time, and — for a delivery report — its `bounce`. Reading never fails on a message. |
94
+ | **UID and UIDVALIDITY** | A message's identity in a folder. Keep both, read on with `after_uid` (or read a whole folder with `messages`), act on messages with `mark`, `move`, `delete`. |
95
+ | **MailError** | Every failure, with a `kind` that says who has to act: `invalid`, `config`, `auth`, `tls`, `unreachable`, `deferred`, `rejected`, or `unknown` when no usable answer came after the whole message was sent. |
96
+
97
+ ## Things to know
98
+
99
+ | | |
100
+ |---|---|
101
+ | **Acceptance is not delivery** | `Sent` is what the submission server took. Unknown recipients often come back later as a bounce; read them with `fetch` and match `bounce.original_message_id`. |
102
+ | **The TLS mode follows the port** | Implicit TLS on 465 and 993, STARTTLS elsewhere, unless `security` (SMTP) and `imap_security` (IMAP) — set independently — say otherwise. A port spoken to in the wrong mode fails at once as `tls`, naming the setting. |
103
+ | **Results are JSON-ready** | `Received`, `Sent`, `Fetched` and the rest are frozen values whose JSON keys are camelCase (`messageId`, `receivedAt`; the author is `"from"`), for storing or queueing; Python code uses the field names. |
104
+ | **Nothing is sent twice by the library** | A session checks its connection before a message and never retries after one; retrying is the caller's decision, guided by `transient`. |
105
+ | **Changes need the folder's UIDVALIDITY** | `mark`, `move` and `delete` refuse UIDs from a folder that has since been rebuilt. |
106
+ | **Providers differ, the model does not** | Relays and mailboxes, a replaced Message-ID, Gmail's delete-means-archive, folders under `INBOX.` — each is handled or documented in [Operating](https://github.com/forktex/forktex-mail/blob/master/docs/operating.md#where-providers-differ). |
107
+
108
+ ## Documentation
109
+
110
+ | Page | For |
111
+ |---|---|
112
+ | [Guide](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md) | Runnable recipes for each way to use it |
113
+ | [Reference](https://github.com/forktex/forktex-mail/blob/master/docs/reference.md) | Every public name, setting and error |
114
+ | [Operating](https://github.com/forktex/forktex-mail/blob/master/docs/operating.md) | Providers, TLS, sending caps, bounces, what to watch |
115
+
116
+ ## Stability
117
+
118
+ From 1.0.0, semantic versioning covers every name in `forktex_mail.__all__`,
119
+ the eight error kinds and the `AppErrorCode` each maps to. Anything else —
120
+ module paths included — is internal. Changes are listed in the
121
+ [CHANGELOG](https://github.com/forktex/forktex-mail/blob/master/CHANGELOG.md).
122
+
123
+ ## Contributing
124
+
125
+ Working on `forktex-mail` itself? Start with
126
+ [`docs/development.md`](https://github.com/forktex/forktex-mail/blob/master/docs/development.md). Security issues go to the
127
+ address in [SECURITY.md](https://github.com/forktex/forktex-mail/blob/master/SECURITY.md).
128
+
129
+ ## Licence
130
+
131
+ AGPL-3.0-or-later, or a commercial licence from FORKTEX S.R.L. See
132
+ [LICENSE](https://github.com/forktex/forktex-mail/blob/master/LICENSE) and [NOTICE](https://github.com/forktex/forktex-mail/blob/master/NOTICE).
133
+
@@ -0,0 +1,101 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/forktex/forktex-mail/master/docs/assets/mail-banner.png" alt="forktex-mail" height="120">
3
+ </p>
4
+
5
+ <p align="center">
6
+ <a href="https://pypi.org/project/forktex-mail/"><img src="https://img.shields.io/pypi/v/forktex-mail.svg" alt="PyPI"></a>
7
+ <a href="https://pypi.org/project/forktex-mail/"><img src="https://img.shields.io/pypi/pyversions/forktex-mail.svg" alt="Python"></a>
8
+ <a href="https://github.com/forktex/forktex-mail/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/forktex-mail.svg" alt="License"></a>
9
+ </p>
10
+
11
+ Send and process e-mail from any Python process — a one-off script, a worker or
12
+ a production API. SMTP sends, one connection per message or one session for
13
+ many; IMAP reads a mailbox incrementally, files, marks, moves and deletes. Every
14
+ failure says who has to act and whether to retry, decided from the codes SMTP
15
+ and IMAP define, never from a provider's wording.
16
+
17
+ ```bash
18
+ pip install forktex-mail
19
+ ```
20
+
21
+ ```python
22
+ from forktex_mail import Mailbox, compose, fetch, send
23
+
24
+ box = Mailbox(host="mail.example.com", user="me@example.com", password="…", sender_name="Me")
25
+
26
+ sent = await send(box, compose(box, to="Ana <ana@example.com>", subject="Hello", text="Hi!", html="<p>Hi!</p>"))
27
+ inbox = await fetch(box, unseen=True)
28
+ ```
29
+
30
+ ## Requirements
31
+
32
+ | | |
33
+ |---|---|
34
+ | **Python** | 3.14 |
35
+ | **A mail server** | Any SMTP submission server to send; IMAP to read, file and process. Battle-tested against Zoho Mail, Postfix and Dovecot, and GreenMail. |
36
+ | **Sign-in** | A password (or an app password), or an OAuth2 access token for providers that require one (Microsoft 365, Outlook.com, Gmail). |
37
+ | **TLS** | Implicit TLS or STARTTLS, verified against the system's authorities or a private one you supply. Plain SMTP only for a local catcher, without credentials. |
38
+
39
+ ## What you can build
40
+
41
+ | You want to | Read |
42
+ |---|---|
43
+ | Describe a mailbox once, from settings or a database row | [A mailbox](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#a-mailbox) |
44
+ | Send from a script, an API or a worker | [Send from a script](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#send-from-a-script), [Send from an API](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#send-from-an-api) |
45
+ | Send many messages on one logged-in connection | [Send many messages](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#send-many-messages) |
46
+ | Attach files, thread replies, add `List-Unsubscribe` | [Attachments, threads and headers](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#attachments-threads-and-headers) |
47
+ | Stay under a host's sending caps | [Stay under a sending cap](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#stay-under-a-sending-cap) |
48
+ | Sign in to Microsoft 365, Outlook.com or Gmail with OAuth2 | [Sign in with OAuth2](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#sign-in-with-oauth2) |
49
+ | Read a mailbox, read on from where you stopped, or read a whole folder in batches | [Read a mailbox](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#read-a-mailbox-and-read-on-later) |
50
+ | File sent mail, mark, move and delete — process an inbox | [Process an inbox](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#process-an-inbox) |
51
+ | Find out which messages bounced, and why | [Read bounces](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#read-bounces) |
52
+ | Decide whether to retry, fix settings or drop a message | [Decide what to do with a failure](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#decide-what-to-do-with-a-failure) |
53
+ | Test your own code that sends mail, without a server | [Test code that sends mail](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md#test-code-that-sends-mail) |
54
+
55
+ ## How it works
56
+
57
+ | Concept | What it is |
58
+ |---|---|
59
+ | **Mailbox** | One account's settings: hosts, sign-in, sender, TLS. Pure data; never reads the environment. |
60
+ | **Transport** | Anything that sends a message, says what the server did, and closes: `Smtp`, or `Capture` in tests. |
61
+ | **Session** | `async with Smtp(mailbox)`: one login for many messages, checked before each and reconnected when gone. |
62
+ | **Received** | A message read back: who it is `from_` and to, text, HTML, attachments, every header, the server's flags and arrival time, and — for a delivery report — its `bounce`. Reading never fails on a message. |
63
+ | **UID and UIDVALIDITY** | A message's identity in a folder. Keep both, read on with `after_uid` (or read a whole folder with `messages`), act on messages with `mark`, `move`, `delete`. |
64
+ | **MailError** | Every failure, with a `kind` that says who has to act: `invalid`, `config`, `auth`, `tls`, `unreachable`, `deferred`, `rejected`, or `unknown` when no usable answer came after the whole message was sent. |
65
+
66
+ ## Things to know
67
+
68
+ | | |
69
+ |---|---|
70
+ | **Acceptance is not delivery** | `Sent` is what the submission server took. Unknown recipients often come back later as a bounce; read them with `fetch` and match `bounce.original_message_id`. |
71
+ | **The TLS mode follows the port** | Implicit TLS on 465 and 993, STARTTLS elsewhere, unless `security` (SMTP) and `imap_security` (IMAP) — set independently — say otherwise. A port spoken to in the wrong mode fails at once as `tls`, naming the setting. |
72
+ | **Results are JSON-ready** | `Received`, `Sent`, `Fetched` and the rest are frozen values whose JSON keys are camelCase (`messageId`, `receivedAt`; the author is `"from"`), for storing or queueing; Python code uses the field names. |
73
+ | **Nothing is sent twice by the library** | A session checks its connection before a message and never retries after one; retrying is the caller's decision, guided by `transient`. |
74
+ | **Changes need the folder's UIDVALIDITY** | `mark`, `move` and `delete` refuse UIDs from a folder that has since been rebuilt. |
75
+ | **Providers differ, the model does not** | Relays and mailboxes, a replaced Message-ID, Gmail's delete-means-archive, folders under `INBOX.` — each is handled or documented in [Operating](https://github.com/forktex/forktex-mail/blob/master/docs/operating.md#where-providers-differ). |
76
+
77
+ ## Documentation
78
+
79
+ | Page | For |
80
+ |---|---|
81
+ | [Guide](https://github.com/forktex/forktex-mail/blob/master/docs/guide.md) | Runnable recipes for each way to use it |
82
+ | [Reference](https://github.com/forktex/forktex-mail/blob/master/docs/reference.md) | Every public name, setting and error |
83
+ | [Operating](https://github.com/forktex/forktex-mail/blob/master/docs/operating.md) | Providers, TLS, sending caps, bounces, what to watch |
84
+
85
+ ## Stability
86
+
87
+ From 1.0.0, semantic versioning covers every name in `forktex_mail.__all__`,
88
+ the eight error kinds and the `AppErrorCode` each maps to. Anything else —
89
+ module paths included — is internal. Changes are listed in the
90
+ [CHANGELOG](https://github.com/forktex/forktex-mail/blob/master/CHANGELOG.md).
91
+
92
+ ## Contributing
93
+
94
+ Working on `forktex-mail` itself? Start with
95
+ [`docs/development.md`](https://github.com/forktex/forktex-mail/blob/master/docs/development.md). Security issues go to the
96
+ address in [SECURITY.md](https://github.com/forktex/forktex-mail/blob/master/SECURITY.md).
97
+
98
+ ## Licence
99
+
100
+ AGPL-3.0-or-later, or a commercial licence from FORKTEX S.R.L. See
101
+ [LICENSE](https://github.com/forktex/forktex-mail/blob/master/LICENSE) and [NOTICE](https://github.com/forktex/forktex-mail/blob/master/NOTICE).
@@ -0,0 +1,47 @@
1
+ # Security Policy
2
+
3
+ ## Reporting a vulnerability
4
+
5
+ Email **info@forktex.com** with details and, where possible, a reproduction. Please do
6
+ not open a public issue for an unfixed vulnerability.
7
+
8
+ ## Supported versions
9
+
10
+ | Version | Supported |
11
+ | --- | --- |
12
+ | 1.x | ✅ |
13
+
14
+ ## Scope
15
+
16
+ - **Credentials** live in `Mailbox.password` and `Mailbox.oauth2_token`, each a
17
+ `SecretStr`: they never appear in `repr()` or `model_dump()`, and
18
+ `redacted()` is the loggable view. The library's own stack frames never hold
19
+ them in plain text; the protocol libraries it calls (`aiosmtplib`, `imaplib`)
20
+ do while signing in, so a traceback captured with local variables — Sentry's
21
+ default — can include them. Scrub frame variables named `password` in such
22
+ tools.
23
+ - **No password crosses an unencrypted connection.** `security="none"` makes SMTP
24
+ refuse a password or token; IMAP never runs without TLS, whatever `security`
25
+ says. STARTTLS, when required, is never skipped — a server that cannot do it
26
+ is a `tls` error. Signing in is one attempt with one mechanism (XOAUTH2,
27
+ PLAIN or LOGIN), always after TLS is up.
28
+ - **`verify_tls=False`** accepts any certificate, including an attacker's. It is
29
+ for tests only; trust a private relay with `ca_pem` instead.
30
+ - **Errors never quote the server.** A `MailError`'s message and `details` are
31
+ fixed text and codes, safe to return to a client — no reply text and no
32
+ folder name; the server's own reply, and the folder concerned, are logged at
33
+ warning level on the `forktex_mail` logger and the reply is kept on the
34
+ error's `__cause__`. A reply can echo an address the server was given.
35
+ - **OAuth2 tokens** are `SecretStr` like passwords and are never logged; obtaining
36
+ and refreshing them stays with the caller.
37
+ - **Removing mail** touches only the UIDs given, and only in a folder whose
38
+ `uid_validity` still matches; a server that cannot remove precisely (no
39
+ UIDPLUS) is refused with nothing changed.
40
+ - **Header injection**: every header value `compose` writes, extra headers
41
+ included, is folded onto one line with control characters removed, and the
42
+ headers it writes itself cannot be overridden.
43
+ - **Received mail is untrusted input.** `parse` and `fetch` decode what a sender
44
+ wrote, HTML and attachments included; render or open them as you would any
45
+ content from a stranger. Parsing never raises on hostile structure — deep
46
+ nesting, unknown charsets — it records a defect instead.
47
+ - **Dependencies** are audited by `fsd audit` (`pip-audit`), part of the gate.