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.
- forktex_mail-1.0.0/AGENTS.md +18 -0
- forktex_mail-1.0.0/CHANGELOG.md +32 -0
- forktex_mail-1.0.0/LICENSE +45 -0
- forktex_mail-1.0.0/NOTICE +18 -0
- forktex_mail-1.0.0/PKG-INFO +133 -0
- forktex_mail-1.0.0/README.md +101 -0
- forktex_mail-1.0.0/SECURITY.md +47 -0
- forktex_mail-1.0.0/docs/assets/mail-banner.png +0 -0
- forktex_mail-1.0.0/docs/development.md +265 -0
- forktex_mail-1.0.0/docs/guide.md +587 -0
- forktex_mail-1.0.0/docs/operating.md +179 -0
- forktex_mail-1.0.0/docs/reference.md +332 -0
- forktex_mail-1.0.0/fsd.toml +67 -0
- forktex_mail-1.0.0/poetry.lock +3911 -0
- forktex_mail-1.0.0/poetry.toml +25 -0
- forktex_mail-1.0.0/pyproject.toml +138 -0
- forktex_mail-1.0.0/scripts/clean.py +60 -0
- forktex_mail-1.0.0/scripts/license_headers.py +103 -0
- forktex_mail-1.0.0/scripts/oldest.py +66 -0
- forktex_mail-1.0.0/scripts/release_check.py +150 -0
- forktex_mail-1.0.0/scripts/smoke.py +64 -0
- forktex_mail-1.0.0/src/forktex_mail/__init__.py +87 -0
- forktex_mail-1.0.0/src/forktex_mail/errors.py +239 -0
- forktex_mail-1.0.0/src/forktex_mail/imap.py +673 -0
- forktex_mail-1.0.0/src/forktex_mail/mailbox.py +254 -0
- forktex_mail-1.0.0/src/forktex_mail/message.py +410 -0
- forktex_mail-1.0.0/src/forktex_mail/py.typed +0 -0
- forktex_mail-1.0.0/src/forktex_mail/ratelimit.py +125 -0
- forktex_mail-1.0.0/src/forktex_mail/smtp.py +409 -0
- forktex_mail-1.0.0/src/forktex_mail/testing.py +94 -0
- forktex_mail-1.0.0/tests/__init__.py +23 -0
- forktex_mail-1.0.0/tests/_containers.py +181 -0
- forktex_mail-1.0.0/tests/conftest.py +56 -0
- forktex_mail-1.0.0/tests/contract/__init__.py +23 -0
- forktex_mail-1.0.0/tests/contract/test_classification.py +922 -0
- forktex_mail-1.0.0/tests/contract/test_json.py +168 -0
- forktex_mail-1.0.0/tests/contract/test_mailbox.py +256 -0
- forktex_mail-1.0.0/tests/contract/test_message.py +472 -0
- forktex_mail-1.0.0/tests/contract/test_public_surface.py +112 -0
- forktex_mail-1.0.0/tests/contract/test_ratelimit.py +146 -0
- forktex_mail-1.0.0/tests/contract/test_reading.py +143 -0
- forktex_mail-1.0.0/tests/contract/test_sending.py +273 -0
- forktex_mail-1.0.0/tests/scripted.py +384 -0
- forktex_mail-1.0.0/tests/usage/__init__.py +23 -0
- forktex_mail-1.0.0/tests/usage/test_bounces.py +48 -0
- forktex_mail-1.0.0/tests/usage/test_connection_settings.py +90 -0
- forktex_mail-1.0.0/tests/usage/test_process_an_inbox.py +101 -0
- forktex_mail-1.0.0/tests/usage/test_sending_and_receiving.py +295 -0
- forktex_mail-1.0.0/tests/usage/test_sending_from_an_api.py +46 -0
- 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.
|
|
Binary file
|