| Name | mailfmt JSON |
| Version |
1.0.4
JSON |
| download |
| home_page | None |
| Summary | Heuristic plain text email formatter. |
| upload_time | 2025-07-18 02:21:34 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
cli
email
formatter
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1>Mail Format</h1>
`mailfmt` is a simple plain text email formatter. It's designed to ensure
consistent paragraph spacing while preserving markdown syntax, email
headers, sign-offs, and signature blocks.
By default, the command accepts its input on `stdin` and prints to
`stdout`. This makes it well suited for use as a formatter with a text
editor like Kakoune or Helix.
<!--toc:start-->
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Output Example](#output-example)
- [Markdown Safety](#markdown-safety)
- [Aerc Integration](#aerc-integration)
<!--toc:end-->
## Features
- Wraps emails at specified columns.
- Automatically reflows paragraphs.
- Squashes consecutive paragraph breaks.
- Preserves:
- Any long word not broken by spaces (e.g. URLs, email addresses).
- Quoted lines.
- Indented lines.
- Lists.
- Markdown-style code blocks.
- Usenet-style signature block at EOF.
- Sign-offs.
- If specified, output can be made safe for passing to a Markdown
renderer.
- Use case: piping the output to `pandoc` to write a `text/html`
message. See [Markdown Safety](#markdown-safety).
## Installation
`mailfmt` is intended for use as a standaole tool. The package is
available on PyPI as `mailfmt`. I recommend using
[uv](https://github.com/astral-sh/uv) or `pipx` to install it so the
`mailfmt` command is available on your path:
```sh
uv tool install mailfmt
```
Verify that the installation was successful:
```sh
mailfmt --help
```
## Usage
```
usage: mailfmt [-h] [-w WIDTH] [-b] [--no-replace-whitespace] [--no-reflow]
[--no-signoff] [--no-signature] [--no-squash] [-m] [-i INPUT]
[-o OUTPUT]
Formatter for plain text email.
"--no-*" options are NOT passed by default.
options:
-h, --help show this help message and exit
-w, --width WIDTH Text width for wrapping. (default: 74)
-b, --break-long-words
Break long words while wrapping. (default: False)
--no-replace-whitespace
Don't normalize whitespace when wrapping.
--no-reflow Don't reflow lines.
--no-signoff Don't preserve signoff line breaks.
--no-signature Don't preserve signature block.
--no-squash Don't squash consecutive paragraph breaks.
-m, --markdown-safe Output format safe for Markdown rendering.
-i, --input INPUT Input file. (default: STDIN)
-o, --output OUTPUT Output file. (default: STDOUT)
Author : Daniel Fichtinger
Contact: daniel@ficd.sh
```
## Output Example
Before:
```
Hey,
This is a really long paragraph with lots of words in it. However, my text editor uses soft-wrapping, so it ends up looking horrible when viewed without wrapping! Additionally,
if I manually add some line breaks, things start to look _super_ janky!
I can't just pipe this to `fmt` because it may break my beautiful
markdown
syntax. Markdown formatters are also problematic because they mess up
my signoff and signature blocks! What should I do?
Best wishes,
Daniel
--
Daniel
daniel@ficd.sh
```
After:
```
Hey,
This is a really long paragraph with lots of words in it. However, my text
editor uses soft-wrapping, so it ends up looking horrible when viewed
without wrapping! Additionally, if I manually add some line breaks, things
start to look _super_ janky!
I can't just pipe this to `fmt` because it may break my beautiful markdown
syntax. Markdown formatters are also problematic because they mess up my
signoff and signature blocks! What should I do?
Best wishes,
Daniel
--
Daniel
daniel@ficd.sh
```
## Markdown Safety
In some cases, you may want to generate an HTML email. Ideally, you'd want
the HTML to be generated directly from the plain text message, and for
_both_ versions to be legible and have the same semantics.
Although `mailfmt` was written with Markdown markup in mind, its intended
output is still the `text/plain` format. If you pass its output directly
to a Markdown renderer, line breaks in sign-offs and the signature block
won't be preserved.
If you invoke `mailfmt --markdown-safe`, then `\` characters will be
appended to mark line breaks that would otherwise be squashed, making the
output suitable for conversion into HTML. Here's an example of one such
pipeline:
```bash
cat message.txt | mailfmt --markdown-safe | pandoc -f markdown -t html
--standalone > message.html
```
Here's the earlier example message with markdown safe output:
```
Hey,
This is a really long paragraph with lots of words in it. However, my text
editor uses soft-wrapping, so it ends up looking horrible when viewed
without wrapping! Additionally, if I manually add some line breaks, things
start to look _super_ janky!
I can't just pipe this to `fmt` because it may break my beautiful markdown
syntax. Markdown formatters are also problematic because they mess up my
signoff and signature blocks! What should I do?
Best wishes, \
Daniel \
-- \
Daniel \
daniel@ficd.sh \
```
## Aerc Integration
For integration with `aerc`, consider adding the following to your
`aerc.conf`:
```ini
[multipart-converters]
text/html=mailfmt --markdown-safe | pandoc -f markdown -t html --standalone
```
When you're done writing your email, you can call the
`:multipart text/html` command to generate a `multipart/alternative`
message which includes _both_ your original `text/plain` _and_ the newly
generated `text/html` content.
Raw data
{
"_id": null,
"home_page": null,
"name": "mailfmt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "cli, email, formatter",
"author": null,
"author_email": "Daniel Fichtinger <daniel@ficd.sh>",
"download_url": "https://files.pythonhosted.org/packages/90/8c/bf9e73b64fb7310d6875792094ab2f07f026467f060e3ff484410e5181ed/mailfmt-1.0.4.tar.gz",
"platform": null,
"description": "<h1>Mail Format</h1>\n\n`mailfmt` is a simple plain text email formatter. It's designed to ensure\nconsistent paragraph spacing while preserving markdown syntax, email\nheaders, sign-offs, and signature blocks.\n\nBy default, the command accepts its input on `stdin` and prints to\n`stdout`. This makes it well suited for use as a formatter with a text\neditor like Kakoune or Helix.\n\n<!--toc:start-->\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Output Example](#output-example)\n- [Markdown Safety](#markdown-safety)\n- [Aerc Integration](#aerc-integration)\n\n<!--toc:end-->\n\n## Features\n\n- Wraps emails at specified columns.\n- Automatically reflows paragraphs.\n- Squashes consecutive paragraph breaks.\n- Preserves:\n - Any long word not broken by spaces (e.g. URLs, email addresses).\n - Quoted lines.\n - Indented lines.\n - Lists.\n - Markdown-style code blocks.\n - Usenet-style signature block at EOF.\n - Sign-offs.\n- If specified, output can be made safe for passing to a Markdown\n renderer.\n - Use case: piping the output to `pandoc` to write a `text/html`\n message. See [Markdown Safety](#markdown-safety).\n\n## Installation\n\n`mailfmt` is intended for use as a standaole tool. The package is\navailable on PyPI as `mailfmt`. I recommend using\n[uv](https://github.com/astral-sh/uv) or `pipx` to install it so the\n`mailfmt` command is available on your path:\n\n```sh\nuv tool install mailfmt\n```\n\nVerify that the installation was successful:\n\n```sh\nmailfmt --help\n```\n\n## Usage\n\n```\nusage: mailfmt [-h] [-w WIDTH] [-b] [--no-replace-whitespace] [--no-reflow]\n [--no-signoff] [--no-signature] [--no-squash] [-m] [-i INPUT]\n [-o OUTPUT]\n\nFormatter for plain text email.\n\"--no-*\" options are NOT passed by default.\n\noptions:\n -h, --help show this help message and exit\n -w, --width WIDTH Text width for wrapping. (default: 74)\n -b, --break-long-words\n Break long words while wrapping. (default: False)\n --no-replace-whitespace\n Don't normalize whitespace when wrapping.\n --no-reflow Don't reflow lines.\n --no-signoff Don't preserve signoff line breaks.\n --no-signature Don't preserve signature block.\n --no-squash Don't squash consecutive paragraph breaks.\n -m, --markdown-safe Output format safe for Markdown rendering.\n -i, --input INPUT Input file. (default: STDIN)\n -o, --output OUTPUT Output file. (default: STDOUT)\n\nAuthor : Daniel Fichtinger\nContact: daniel@ficd.sh\n```\n\n## Output Example\n\nBefore:\n\n```\nHey,\n\nThis is a really long paragraph with lots of words in it. However, my text editor uses soft-wrapping, so it ends up looking horrible when viewed without wrapping! Additionally,\nif I manually add some line breaks, things start to look _super_ janky!\n\nI can't just pipe this to `fmt` because it may break my beautiful\nmarkdown\nsyntax. Markdown formatters are also problematic because they mess up\nmy signoff and signature blocks! What should I do?\n\nBest wishes,\nDaniel\n\n-- \nDaniel\ndaniel@ficd.sh\n```\n\nAfter:\n\n```\nHey,\n\nThis is a really long paragraph with lots of words in it. However, my text\neditor uses soft-wrapping, so it ends up looking horrible when viewed\nwithout wrapping! Additionally, if I manually add some line breaks, things\nstart to look _super_ janky!\n\nI can't just pipe this to `fmt` because it may break my beautiful markdown\nsyntax. Markdown formatters are also problematic because they mess up my\nsignoff and signature blocks! What should I do?\n\nBest wishes,\nDaniel\n\n-- \nDaniel\ndaniel@ficd.sh\n```\n\n## Markdown Safety\n\nIn some cases, you may want to generate an HTML email. Ideally, you'd want\nthe HTML to be generated directly from the plain text message, and for\n_both_ versions to be legible and have the same semantics.\n\nAlthough `mailfmt` was written with Markdown markup in mind, its intended\noutput is still the `text/plain` format. If you pass its output directly\nto a Markdown renderer, line breaks in sign-offs and the signature block\nwon't be preserved.\n\nIf you invoke `mailfmt --markdown-safe`, then `\\` characters will be\nappended to mark line breaks that would otherwise be squashed, making the\noutput suitable for conversion into HTML. Here's an example of one such\npipeline:\n\n```bash\ncat message.txt | mailfmt --markdown-safe | pandoc -f markdown -t html\n--standalone > message.html\n```\n\nHere's the earlier example message with markdown safe output:\n\n```\nHey,\n\nThis is a really long paragraph with lots of words in it. However, my text\neditor uses soft-wrapping, so it ends up looking horrible when viewed\nwithout wrapping! Additionally, if I manually add some line breaks, things\nstart to look _super_ janky!\n\nI can't just pipe this to `fmt` because it may break my beautiful markdown\nsyntax. Markdown formatters are also problematic because they mess up my\nsignoff and signature blocks! What should I do?\n\nBest wishes, \\\nDaniel \\\n\n-- \\\nDaniel \\\ndaniel@ficd.sh \\\n```\n\n## Aerc Integration\n\nFor integration with `aerc`, consider adding the following to your\n`aerc.conf`:\n\n```ini\n[multipart-converters]\ntext/html=mailfmt --markdown-safe | pandoc -f markdown -t html --standalone\n```\n\nWhen you're done writing your email, you can call the\n`:multipart text/html` command to generate a `multipart/alternative`\nmessage which includes _both_ your original `text/plain` _and_ the newly\ngenerated `text/html` content.\n",
"bugtrack_url": null,
"license": null,
"summary": "Heuristic plain text email formatter.",
"version": "1.0.4",
"project_urls": {
"Repository": "https://git.ficd.sh/ficd/mailfmt"
},
"split_keywords": [
"cli",
" email",
" formatter"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb09cbafb6a26bda67e5fcb22af07b2709aae39dcece98927fbf23f881420f4e",
"md5": "6410fae0d2fb97209e9b5a21cc4f7be4",
"sha256": "5d9943c53d8c993b38f82bc39edd1b80df50d978cfbe53caea4a0fc3b1fe969f"
},
"downloads": -1,
"filename": "mailfmt-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6410fae0d2fb97209e9b5a21cc4f7be4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 5887,
"upload_time": "2025-07-18T02:21:34",
"upload_time_iso_8601": "2025-07-18T02:21:34.228455Z",
"url": "https://files.pythonhosted.org/packages/eb/09/cbafb6a26bda67e5fcb22af07b2709aae39dcece98927fbf23f881420f4e/mailfmt-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "908cbf9e73b64fb7310d6875792094ab2f07f026467f060e3ff484410e5181ed",
"md5": "bd59bd030cd8be1f94f99e6c1824b791",
"sha256": "ad979921f16f4aede37d1fbb5a90ecf12e10f54dfeb9638c9aaff297136cb4fe"
},
"downloads": -1,
"filename": "mailfmt-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "bd59bd030cd8be1f94f99e6c1824b791",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 6864,
"upload_time": "2025-07-18T02:21:34",
"upload_time_iso_8601": "2025-07-18T02:21:34.939121Z",
"url": "https://files.pythonhosted.org/packages/90/8c/bf9e73b64fb7310d6875792094ab2f07f026467f060e3ff484410e5181ed/mailfmt-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 02:21:34",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mailfmt"
}
