| Name | mailfmt JSON |
| Version |
1.0.3
JSON |
| download |
| home_page | None |
| Summary | Heuristic plain text email formatter. |
| upload_time | 2025-07-13 06:51:33 |
| 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.ca>",
"download_url": "https://files.pythonhosted.org/packages/1a/0e/ddb9c655fcde250ee59adda7ad6bf73009d905d142ae17558c280bf0f79c/mailfmt-1.0.3.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.3",
"project_urls": {
"Repository": "https://git.ficd.sh/ficd/mailfmt"
},
"split_keywords": [
"cli",
" email",
" formatter"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1337c57ebd4e99fdee36d518ba15617023389526f7e996e03d6672cf0704e1fc",
"md5": "1e8cfd89df42947ddcebde503d8877a3",
"sha256": "be1aab8f7d647e2deff166c7ba0adbeccda5890a51af581313f607b6a0b0fb77"
},
"downloads": -1,
"filename": "mailfmt-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1e8cfd89df42947ddcebde503d8877a3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 5817,
"upload_time": "2025-07-13T06:51:33",
"upload_time_iso_8601": "2025-07-13T06:51:33.070864Z",
"url": "https://files.pythonhosted.org/packages/13/37/c57ebd4e99fdee36d518ba15617023389526f7e996e03d6672cf0704e1fc/mailfmt-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1a0eddb9c655fcde250ee59adda7ad6bf73009d905d142ae17558c280bf0f79c",
"md5": "5754edbe968ed5ca9257981156c41625",
"sha256": "0de3f6f47e04852b667fff8ac251b91371ef130451c8077c168aafe1a4c6f1ef"
},
"downloads": -1,
"filename": "mailfmt-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "5754edbe968ed5ca9257981156c41625",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 6557,
"upload_time": "2025-07-13T06:51:33",
"upload_time_iso_8601": "2025-07-13T06:51:33.876405Z",
"url": "https://files.pythonhosted.org/packages/1a/0e/ddb9c655fcde250ee59adda7ad6bf73009d905d142ae17558c280bf0f79c/mailfmt-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 06:51:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mailfmt"
}
