{"id":13815182,"url":"https://github.com/arachsys/mailwrap","last_synced_at":"2025-05-15T07:32:05.394Z","repository":{"id":15532348,"uuid":"18266960","full_name":"arachsys/mailwrap","owner":"arachsys","description":"Text filling and wrapping plugin for Apple Mail","archived":false,"fork":false,"pushed_at":"2023-01-28T17:28:48.000Z","size":39,"stargazers_count":74,"open_issues_count":1,"forks_count":10,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-11-19T10:48:54.747Z","etag":null,"topics":["email","macos","plugin"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arachsys.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-03-30T15:30:55.000Z","updated_at":"2024-08-08T08:46:22.000Z","dependencies_parsed_at":"2023-02-15T18:01:27.571Z","dependency_job_id":null,"html_url":"https://github.com/arachsys/mailwrap","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arachsys%2Fmailwrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arachsys%2Fmailwrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arachsys%2Fmailwrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arachsys%2Fmailwrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arachsys","download_url":"https://codeload.github.com/arachsys/mailwrap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254295964,"owners_count":22047179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","macos","plugin"],"created_at":"2024-08-04T04:03:05.948Z","updated_at":"2025-05-15T07:32:02.496Z","avatar_url":"https://github.com/arachsys.png","language":"Python","readme":"MailWrap\n========\n\nMailWrap is a plugin for Apple Mail on macOS 10.12 to 12.x, making it\neasier to compose well-formed and correctly wrapped plain text messages. It\nintroduces line wrapping and paragraph filling operations, and extends the\nbuilt-in indentation functions to work in plain text mode.\n\nMail was once quite a good 'net citizen. It could be configured to generate\nplain text email, and would do so with the text neatly wrapped at 76\ncolumns. In addition, it used the RFC2646 format=flowed extension to\nindicate that these wrapped paragraphs could be reflowed. Thus mailing list\narchives and traditional mail clients saw readable 80-column text without\nnoisy encoding, but more sophisticated readers could re-fill the paragraphs\nto suit the display width.\n\nUnfortunately, Mail is poorly maintained and has declined in quality over\nrecent years, with many bugs introduced and incompetent design choices made.\nCurrent releases have ditched format=flowed for plain text parts, instead\nopting to emit each paragraph as a single long line. If this is longer than\n77 characters, the text is mangled with a quoted-printable transfer\nencoding. The resulting email leaves a very visible mess in mailing list\narchives on the web, as well as drawing understandable ire from recipients\nwith traditional unix mail clients.\n\nFortunately, even if Mac users find themselves drawn to Apple Mail for its\nconvenient reading interface and good platform integration, all is not lost.\nIf lines are no longer than 77 characters, Mail won't use quoted-printable\nin your outgoing messages, resulting in perfectly acceptable plain text\nemail that won't embarrass you in public. Manual paragraph filling is\ntedious and time-consuming, but the MailWrap plugin can help automate the\njob.\n\nAn alternative, more automatic solution to the same problem is implemented\nin the MailFlow plugin, which reimplements format=flowed in Mail and\neliminates quoted-printable plain text email under most circumstances. It is\navailable from\n\n  https://github.com/arachsys/mailflow\n  https://bitbucket.org/arachsys/mailflow\n\nalongside this plugin. The two plugins can now happily coexist.\n\n\nCompatibility\n-------------\n\nMailWrap is currently compatible with Apple Mail 10.0 to 15.x included in\nmacOS 10.12 (Sierra) to 12.x (Monterey).\n\nIt does not yet support Mail 16.x included in macOS 13.x (Ventura). This\nmakes major changes to the message editor, requiring non-trivial fixes to\nthe way MailWrap hooks into the composer. In particular, it is no longer\nobvious how to access the message DOM tree, which MailWrap relies on to\ncorrect attribution lines, detect plain text mode and extend indentation.\n\nI do not use macOS apart from maintaining MailFlow and MailWrap, and only\nhave occasional access to machines running the most recent versions. As far\nas I can tell, the class-dump utility which I relied on to develop MailWrap\nis also broken by the latest OS release. I would welcome input from anyone\nwith better insight into the Mail.app changes, or just with more patience\nto reverse-engineer its internals once again. Please do get in touch with\nChris Webb \u003cchris@arachsys.com\u003e.\n\n\nInstallation\n------------\n\nTo install, clone the git repository or unpack the source tar.gz, change to\nthe source directory and run 'python install.py' or 'python3 install.py'.\nYour terminal will need access to ~/Library/Mail/Bundles/ which you can\ngrant in the Privacy and Security tab of System Settings.\n\nThe installer and plugin work with both the system Python 2.7 and more\nrecent Python 3.x, but py2app and pyobjc are required. The installer will\nprompt you to install these with pip/pip3 if they can't be found.\n\nPlugin bundles contain a list of UUIDs identifying versions of Mail with\nwhich they are compatible. The install.py script extracts the correct UUID\nfrom the installed version of Mail, generates a MailWrap.bundle to match,\nand installs it in ~/Library/Mail/Bundles/. You will need to quit and\nrelaunch Mail for the plugin to be registered.\n\nOn macOS 10.14 and later, the plugin must be explicitly enabled in Mail\nPreferences or Settings. Choose 'Manage Plug-ins...' from the General tab,\ntick MailWrap.mailbundle, then choose 'Apply and Restart Mail'.\n\nOn macOS 11.0 and later, the plugin also needs to be ad-hoc signed and\nauthorised before it will work. The installer will run\n\n  codesign -f -s - ~/Library/Mail/Bundles/MailWrap.mailbundle\n  spctl --add --label MailWrap ~/Library/Mail/Bundles/MailWrap.mailbundle\n  spctl --enable --label MailWrap\n\nfor you, but spctl will require your password to allow the changes. Many\nthanks to A. Wilcox (awilfox) for providing these signing instructions on\ntheir Cat Fox Life blog.\n\nIf the sandbox doesn't allow Mail.app to read the directory where your\nPython is installed, you may need to change 'semi_standalone' to False in\nthe setup options in install.py. This issue doesn't affect /usr/bin/python\nor /usr/bin/python3, but has been reported with Homebrew Python running\nfrom /opt/homebrew/bin/python3 and /opt/homebrew/Cellar/python@3.x/.\n\nIf you use the system Python 2.7 on macOS 11.0 or later, you will need to\nset SYSTEM_VERSION_COMPAT=0 in the environment when running install.py:\n\n  SYSTEM_VERSION_COMPAT=0 /usr/bin/python install.py\n\nWithout this, a horrible Apple hack will cause the installer to detect the\nOS version incorrectly as 10.16. It aborts with a warning if that happens.\n\nSometimes when Mail is updated, its compatibility UUID changes. Mail will\nthen disable plugins, moving them from 'Bundles/' to 'Bundles (Disabled)/'.\nThe user is notified when this happens, and it is sufficient to simply run\nthe install.py script again. The old disabled bundle will be cleared away,\nand a new one built and installed to match the new version of Mail.\n\n\nFeatures\n--------\n\nTwo new items are appended to the Edit menu, 'Fill Text' and 'Wrap Text',\nwith key-bindings Command-\\ and Option-Command-\\.\n\nFill Text reformats the current paragraph block to the configured width,\ntreating a block of lines separated by spaces or a change in quote level as\na single paragraph. If a block of text is selected, all paragraphs which\noverlap the selection are filled.\n\nThis operation preserves quote level, allowing for the quote characters in\nthe fill width, and if the first line is indented by one or more spaces,\nsubsequent lines will be indented with spaces to the same column. Exactly\none blank line is left between the formatted paragraph and the next.\n\nSimilarly, Wrap Text wraps the current line to the configured width,\nretaining any leading indent and the quote level on any continuation lines.\nIf a block of text is selected, all lines which overlap the selection are\nwrapped.\n\nMailWrap also fixes the built-in Increase/Decrease Indentation operations to\nwork on plain text messages. These will insert or remove a configurable\nnumber of spaces at the start of the current line or all lines overlapping\nthe current selection.\n\nFinally, by default MailWrap will trim the excessively verbose attribution\nline Mail inserts when composing a reply, i.e.\n\n  On 8 Apr 2014, at 10:08:34, Chris Webb \u003cchris@arachsys.com\u003e wrote:\n\n will become just\n\n  Chris Webb \u003cchris@arachsys.com\u003e wrote:\n\nSince version 8.0, Mail has a bug which causes the attribution line to be\nquoted as if it were part of the original message. MailFlow will also fix\nthis whilst trimming the attribution line.\n\nThis behaviour can be disabled in the preferences.\n\n\nConfiguration\n-------------\n\nMailWrap reads a handful of preferences from the com.apple.mail domain.\nThese can be set at the command line with the macOS defaults command:\n\n  defaults write com.apple.mail MailWrap -dict-add BulletLists -bool false\n  defaults write com.apple.mail MailWrap -dict-add BulletLists -bool true\n    - configure MailWrap to interpret '- ', '+ ' or '* ' at the start of a\n      paragraph as introducing a bullet item and so indent subsequent lines\n      appropriately. The default is on.\n\n  defaults write com.apple.mail MailWrap -dict-add FixAttribution -bool false\n  defaults write com.apple.mail MailWrap -dict-add FixAttribution -bool true\n    - configure MailWrap to strip the verbose date and time information\n      from the attribution line when composing a reply. The default is on.\n\n  defaults write com.apple.mail MailWrap -dict-add IndentWidth -int NN\n    - configure MailWrap to increase/decrease plain text indentation by NN\n      spaces when Command-] and Command-[ are used. The default is 2.\n\n  defaults write com.apple.mail MailWrap -dict-add WrapWidth -int NN\n    - wrap lines and fill paragraphs at a width of NN characters. The\n      default is 76, which is short enough that Mail won't inflict a\n      quoted-printable transfer encoding on the message text.\n\n\npbmbox\n------\n\nFor command-line users, the MailWrap distribution also includes a small\nutility, pbmbox. When messages are selected and copied in Mail, they are\nadded to the clipboard as RFC822MessageDatasPboardType objects. pbmbox\ndecodes these objects and emits the messages in unix mbox format on stdout.\n\nTo install, copy it to a directory in your PATH and make it executable:\n\n  sudo install -m 0755 pbmbox.py /usr/local/bin/pbmbox\n\nA typical use is importing a patch series from email into a git repository.\nSelect the messages in Mail, copy them with Command-C, and then run\n\n  pbmbox | git am\n\nwithin the repository.\n\nBy default, the mboxrd format is used: lines beginning with /\u003e*From / are\nquoted with one additional leading '\u003e'. This encoding avoids corruption of\nmessages and is always reversible. If the -n or --no-quote-from option is\ngiven, pbmbox will not attempt to quote 'From  ' lines. This is sometimes\nuseful for simple command-line handling of a single message, where no\nambiguity can result from an unquoted 'From '.\n\n\nImplementation notes\n--------------------\n\nApple haven't done everything wrong in Mail. Writing this plugin would be\nnear-impossible had their mail client not been furnished with a plugin\ninterface, albeit an undocumented one. The reading interface is nice, with\ngood platform integration, fast full-text search and cross-mailbox\nthreading.\n\nCurious readers of the code may be surprised by the long-winded approach\ntaken in manipulating the message text. The editor is a WebKit editable\nview, for both rich text (HTML) and plain text messages, and it is certainly\npossible (and more efficient) to directly manipulate and modify the\nunderlying DOM tree. However, MailWrap deliberately takes another approach,\nsticking to the simple NSResponder interface which offers simple operations\nsuch as moveToBeginningOfParagraph:, moveToEndOfParagraphAndModifySelection:\nand insertText:.\n\nThis is not due to a perverse desire to use the most awkward interface or\nwrite the least efficient wrapping code possible! When manipulating the\nmessage in simple ways that would not possible through the UI, it turns out\nto be very easy to get Mail into a confused state, where for instance the\nmessage looks fine in the editor but has unintended blank lines when\nrendered to plain text upon sending. The BLOCKQUOTE elements used to\nimplement quoting are particularly fussy in this regard.\n\nEven using the NSResponder interfaces, it is necessary to insert a temporary\npadding space at the beginning of a paragraph before selecting and replacing\nthe rest of the text to avoid problems with lost quote level on the second\nand subsequent lines of the reformatted paragraph. (Of course, this means\nthat this is a bug that can be triggered directly from normal user input at\nthe keyboard; I have reproduced and reported it to Apple in this form.)\n\nAn additional benefit of sticking to basic interfaces is that they are less\nlikely to change, disappear or develop significant bugs in future updates of\nMail.\n\n\nCopying\n-------\n\nThis software was written by Chris Webb \u003cchris@arachsys.com\u003e and is\ndistributed as Free Software under the terms of the MIT license in COPYING.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farachsys%2Fmailwrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farachsys%2Fmailwrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farachsys%2Fmailwrap/lists"}