PyMailGUI - User Guide (original) (raw)

[](docetc/docimgs/index.html)	PyMailGUI — Email Without the Evil

News

PyMailGUI's source-code and macos-app packages (only) were updated and rereleased in June 2022, to add a Message-ID header to all sent mails, use Reply-To if resent, throttle down event checks, and more; see the full release description ahead. Linux and Windows users: your executables were not rebuilt; please use the source-code package per below.

Contents

• Introducing PyMailGUI
  • PyMailGUI's Features
  • PyMailGUI's Intangibles
  • About This Release
    
• Usage Basics
  • Install and Launch
  • Configuration
  • Offline Mode
    
• A Brief Guide to the GUI
  • General Layout
  • List Windows
  • View and Compose Windows
    
• Assorted Hints
• Recent Updates
  • Upgrading PyMailGUI
  • PyMailGUI Changes
    
• For More Details

Welcome to _PyMailGUI_—a basic but useful and private email client, that runs as a desktop GUI on your computer. It allows you to process your email both live at your account's POP/SMTP servers, and offline in locally saved files; is available in both self-contained executable and transparent source-code formats; and works the same on macos, Windows, and Linux per the screenshots above. While PyMailGUI does not directly support IMAP, HTML emails, or emojis, it continues to work well as a no-nonsense and go-to email client after two decades.

Among its most valuable assets, PyMailGUI is dedicated to the notion that your email is your business. With PyMailGUI, you can read, send, and save your email on your own computer—without logging in to an online session that someone else controls; without being bombarded by rude advertising; and without your activity being tracked by those who see your personal communications as assets to exploit. If this stuff matters to you, PyMailGUI may be the email client you've been looking for.

PyMailGUI is coded with Python 3.X and its tkinter library. It's available as a Mac app and Windows and Linux executables for ease of use, as well as complete and portable open-source code that ensures transparency. While apps and executables integrate best with your computer's GUI, source code means that PyMailGUI can never do something you cannot see.

As a desktop GUI, PyMailGUI runs locally on your computer, and fetches and sends emails only on request using your configured email account's POP and SMTP servers, respectively. It comes with features including those in the following table.

Because this program was originally coded as an example for a book, it intentionally omits some more advanced features such as spell checkers, HTML email composition tools, inline HTML viewing (it spawns a browser for HTML content), address books, email sorting and searching, and direct IMAP support. Extensions remain suggested exercises.

Despite its design limits, though, the program has been sufficient to serve as its maker's primary business and personal email tool for over two decades. It comes with everything you need to take control of your email experience.

Perhaps most importantly, PyMailGUI provides a degree of privacy that many popular email clients do not. PyMailGUI never connects to the Internet, except to momentarily fetch and send emails, and only on your request. This means that your email session is offline—and immune to prying eyes and marketers. Especially when using PyMailGUI to access a private email account, your email is your property, not something to be scanned and monetized by self-interested people. While PyMailGUI cannot guarantee complete email privacy (and servers are still open to abuse), it does deliver email sessions that are both ad-free and snoop-free.

True to its book-example heritage, PyMailGUI is also partly intended to serve in an educational role. Users interested in programming are invited to consider its amply documented code, which spans 15K source lines (at latest count) developed incrementally in the book and greatly enhanced later, as an example that demonstrates larger-scale Python programming techniques.

This standalone release uses code based on that in the book, but reused packages are nested within PyMailGUI's folder, and a new launcher and per-account configuration files reside at the top of the package. In the book, both PyMailGUI and packages it uses are part of a larger PP4E package tree, and the launcher is nested within PyMailGUI. This release has also evolved substantially since its book-example genesis, and is aimed at both book readers and others looking for a private email-client solution.

PyMailGUI's standalone-release code is available both in its zipfileand online, per the next section.

This section provides points on installing, launching, configuring, and using the program itself. The shortest version of this story is that to use PyMailGUI, you'll:

1. Install one of its distribution packages—app, executable, or source
2. Setup your email accounts in one or more files in the MailConfigs folder
3. Run the program to access your server-hosted or locally saved email Details on all of the above follow to help get you started. If you just want to test-drive the system, you can skip configuration for now and open one of the saved-mail files shipped with the system, as described ahead. You'll eventually need to configure your own email account's parameters to send or receive email live.

PyMailGUI runs the same on macos, Windows, and Linux. It's distributed in both self-contained "frozen" app and executable formats, as well as complete source code, available from this site. If you consider yourself more user of software than developer of software you may prefer one of the standalone formats for each platform you work on, though the source-code package is portable and may be more recent. In more detail, the tradeoffs are these:

• The frozen packages run on just one platform each, but mesh best with your computer's GUI, require no additional installs, and are immune to changes in other installed software.
• The source-code package requires a separate Python install on each platform you wish to use, but the code itself runs on all PyMailGUI platforms, may have new upgrades that other packages lack, and supports both inspection and changes.

In other words, unless you plan on spelunking though the program's code or require the latest enhancements, one of the frozen packages are probably your best bet.

Once you've fetched your PyMailGUI, install and launch details vary per package. Frozen apps and executables do both with a click or two, but source-code requires extra steps.

For the frozen packages:

1. Download the zipfile for your platform fromhere
2. Unzip to a folder on your computer to install
3. Click on the folder's app or executable to run: PyMailGUI.app on macos, PyMailGUI.exe on Windows, or PyMailGUI on Linux

For the source-code package:

1. Download the source-code zipfile from here
2. Unzip to a folder on your computer to install
3. Also install a Python 3.X to run PyMailGUI if one isn't already present: get Python here
4. Also install a tkinter/Tk GUI toolkit if required on your platform, per ahead
5. Launch the program's main script, Launch_PyMailGUI.py on any platform, using normal Python techniques: command line, file icon click, or IDE run For source-code users, this program has been verified to run on Python 3.1 through 3.8; it is expected work with later versions, but Python changes frequently, so get 3.8 if issues arise. Also note that Python comes tkinter/Tk included on Windows; Mac users may wish to consult this and this; and Linux usually has a tkinter/Tk installed, but see your software repositories if needed.

After installing PyMailGUI per the above, your next step is to configure your email accounts—the topic of the next section.

Apart from installing PyMailGUI, some configuration is required if you wish to connect to your own email accounts. You can safely use the defaults or any example mail configuration file shipped with the program to experiment with the GUI or work offline, but must setup a configuration file with your own account parameters to send or receive email.

Mail configuration files are coded in Python for flexibility, and are located in the installed program's folder. This folder contains one file per account you wish to access; its files' names become entries in the account launcher GUI that opens when you first start the system.

The mapping from file to account is described in full in the MailConfigsfolder's README.txt, but in short:

• Each account is represented by a MailConfigs file of Python assignments which set variables expected by the program.
• Account files are named mailconfig_XXX.py, where XXXis the name that shows up in the launcher's selections list.
• When you open an account by name in the launcher, its MailConfigs file is run to setup the account's parameters. The account files in MailConfigs are a series of simple assignment statements which give account login parameters (e.g., server addresses and usernames), and optional GUI behavior preferences (e.g., fonts and colors). See the example files shipped for typical account-specific settings, and the PyMailGui-PP4E folder's mailconfig.pyfor the full set of available configuration settings. The latter of these is known as the base file, and is used if the empty "defaultbase" account example is selected in the launcher.

More generally, mail configuration files are coded as a hierarchy. Settings in the base file provide defaults that apply globally to all accounts' sessions, but settings in an account-specific file you provide in MailConfigs pertain to just that account's sessions. Your mailconfig_XXX.py files' assignments implicitly override and replace the default settings in the base file, for a specific account's parameters and preferences. For instance, to run PyMailGUI on your Gmail account live, emulate or tailor mailconfig_Gmail.py, select "Gmail" in the launcher GUI and press its Open Account.

For more details on configuration, see the MailConfigsfolder's README, and edit or emulate the shipped examples for your own accounts. Any example account file may be freely edited or replaced, and can be used to experiment with the system offline—per the next section.

While file changes allow you to connect to your account servers, they are not required for offline use. Offline mode allows you to process mails saved in files on your computer, using any account's configurations file—including the examples shipped. The program does not connect to any server unless and until mail is fetched or sent, and all the example account files shipped require a password on initial connections. Passwords are not provided for the example accounts (and you're unlikely to guess correctly!).

See the PyMailGui-PP4E folder's SavedMailsubfolder for example saved-mail files to view offline via the GUI's "Open" buttons. You can also view your _sent_mail offline, as described ahead. Now that you've learned about installing and configuring PyMailGUI, though, it's time to jump in to its GUI to do some email.

This section provides a quick rundown on the GUI's operation. Clicks its thumbnails and links along the way to view example windows. For space the linked shots here are all from the Mac app, but you'll find equivalents for your platform of choice in the complete screenshots collection.

PyMailGUI allows you to both send and receive emails from any of your accounts' servers, and work with saved-mail files completely offline. When started, it first displays a launcher window, from which you can open email accounts specified by your MailConfigsfolder files that we met earlier.

For each account that you spawn with the launcher's Open Account button, PyMailGUI provides an independently running multiwindow GUIthat consists of:

1. A main mail list window for the mail at your server
2. Any number of mail list windows for local saved-mail files
3. Any number of message view and compose windows

View and compose windows use the PyEdit program for display and edit of a message's main text (more on this ahead). Additional popup windows—including mail raw-text, file selection, password prompts, and transfer status—appear when needed. If a console window is supported by your install package (e.g., source code), it is also used for program trace messages that can be safely ignored by most users.

In general, most mail-processing operations can _overlap in time_—for instance, you can compose and sendmultiple emails while a load of received messages is in progress—though some transfers preclude starting others. The GUI will let you know if a new operation must wait for others to finish. The next two sections cover the two main types of windows you'll use in PyMailGUI.

Mail list windows, opened from the launcher's window, are your top-level interface to both:

• Emails received and stored on your account's server (i.e., your email provider)
• Emails you have accessed and saved locally in one or more files on your computer

These windows look and act almost entirely the same, but saved-mail lists have no load button because there are no incoming messages to fetch, and only the server window has a top-of-window help bar (this plus window title helps make them distinct). Both types of list windows display just enough header information to help you identify messages, with a leading "*" to indicate attachments. Both also provide two sets of action buttons and event triggers:

• Non-message actions that do not operate on selected mails
• Message actions that apply to mails you've selected in the list In either case, actions are mapped to either your server or saved-mail messages, depending on the type of list window you are using. For example, a delete in the server window deletes the message from your account server, while a delete in a saved-mail file window deletes the massage from the local file. All other message actions, such as views and replies, are similarly applied to server or file mails.

Both widow types also have a Quit button works the same as a window close, and varies by type: a Quit in a saved-mail file list window closes just that window, but a Quit in the server list window checks for unsaved changes in any mail composition window and exits the program on verification. The next two sections provide a more formal reference to list-window actions.

Non-message Actions

The following list-window options are global in scope—they do not apply to selected emails:

For speed, Load fetches just newly arrived email headers from your POP server after the initial load. The full content of server mails is fetched only when first accessed (e.g., by the first View, Reply, or Save in a session), and mails are never automatically retained on your computer or removed from the mail server (use Save and/or Delete as desired).

As usual for general GUIs, you can open multiple saved-mail files in independent list windows via Open buttons in any list window. Changes in saved-mail file content (e.g., via Save and Delete) are reflected in their open list windows immediately.

Message actions

In the mail list window of the server or any saved-mail file, you can process one or more emails with the following buttons and operations:

Per the last row above, list windows support multiple selections. When used, the above operations are automatically applied to all selectedmessages on either the server or in a saved-mail file, depending on the window's type. For example, you fetch and open multiple mails from your account server at once by selecting them in the server-list window and pressing View. Use a single click to select one mail; Ctrl/control-click to select others; Shift-click to select a range of mails; and the All button to select all (or none).

Multiple selections also make it easy to manage mails offline as a group. For instance, you can also both save multiple server mails to saved-mail files, and copy or move multiple saved mails to another new or existing saved-mail file:

• To save to a file initially, select email(s) in a server list window, and click Save.
• To copy to another file, select email(s) in a saved-mail list window, and click Save.
• To move to another file, select email(s) in a saved-mail list window, and click Save and then Delete.

Tip: for maximum privacy, save your new emails to local files, delete them from your account server, and use the actions listed above to manage them. Your local saved-mail files can be used to categorize your mail much like mail folders on some IMAP servers, but are completely offline.

Note that Open and Save in list windows process messages in saved-mail files, while Open and Save in the text area of view and compose windows process the main text part of individual messages; see ahead for more on the distinction.

List windows can be resized, minimized, and scrolled freely and independently, and show you which messages you can access on an account's server or in a local saved-mail file; to view and send actual email content, you'll use the next section's windows.

View and compose windows, opened by buttons in list windows, are your interface to individual messages displayed in server or save-file list windows. View and compose windows are similar, but their topmost actions and components vary for their different roles:

View windows

like this oneare created by selecting an existing message in a server or saved-mail list window and pressing View to open a formatted display. View windows have action buttons to list attached mail parts and split them off into a folder for easy access, along with a row of part-view buttons that allow you to open each component of the mail (including safe attachments) with a single click.

Compose windows

like this oneare created by pressing any list window's Write to start a new mail, or selecting an existing message in a server or saved-mail list window and pressing Reply or Fwd to start a reply or forward. Compose windows have action buttons to list already-attached parts, attach new parts, and send the mail, but no part-view button row. Replies and forwards are identical to writes, but are prefilled with headers and an existing mail's quoted text.

The upper portion of both window types includes the message's most-common header fields for display or entry (Ctrl or command + C/V work in these to cut/paste text). The lower portion of both window types automatically uses the PyEdit program's text-editor component for both display and composition of an email's main message text. Click the PyEdit Help button in this area of the window for more details on using its editing tools omitted here for space (they're mostly intuitive) PyMailGUI also uses PyEdit popup windows to display raw mail text and some HTML parts' text.

On window close (and the Cancel button, which runs the same code), both view and compose windows notify you of unsaved changes in just that window and close the window if verified. By contrast, a window close or Quit in the server list window notifies you of unsaved changes in any PyEdit component or popup window before shutting down if verified. The following sections summarize view and compose windows' actions.

View-window actions

View windows—opened by list-window View buttons—are designed to present a mail's main text and any number of attached parts. Specifically, they display action buttons; header fields; a row of buttons that open individual mail parts (a.k.a. attachments); and a _PyEdit_text-editor component displaying the main text part (or, for HTML-only emails, text extracted from the HTML which is also displayed in a popped-up browser).

View window Parts and Split buttons list and save all mail parts, respectively. To open individual email parts, click their names in the part-buttons row below the header. These open in programs appropriate for the part's filetype, subject to yourMailConfigs settings. For example, text parts open in a PyEdit popup; the HTML version of a text/HTML alternative email opens in a webbrowser; and an attached imageopens in your local viewer.

Compose-window actions

Compose windows—opened by list-window Write, Reply, and Fwd buttons—are similar to view windows, but there is no part-button row; the PyEdit component and header fields are used for entry instead of display (and possibly prefilled, depending on the composition type); and the Split button is replaced with Attach and Send controls, for attaching new parts and sending the mail via your SMTP server, respectively.

PyEdit main-text actions

In addition to PyMailGUI actions described in the two preceding sections, view and compose windows also inherit all the operations supported by the PyEdit component used to display a mail's main text in the lower part of the window, including the following.

This concludes our tour of the GUI in PyMailGUI, but there's more to say about common operations you can perform with the program. For a brief tour of these topics, let's move on to the next section.

This section provides a collection additional task-oriented usage pointers. It's a bit random, and in some parts redundant with other sections of this document, but it may connect some PyMailGUI dots that you hadn't considered before.

Message Save versus text Save: drafts

A Save in a list window saves entire messages (all those selected), and always appends them to the saved-mail file you select in a GUI dialog. By contrast, a Save in the text area of a view/compose windowsaves just that mail's main text part displayed. The latter can be used as a manual _drafts_-saving tool (save to a file, open or copy-paste later). For text-part saves, you can generally use the default Unicode encoding when prompted (per PyEdit's customizable support; see its Help).

Message Open versus text Open

Like the prior note, an Open in a PyMailGUI list window opens a saved-mail file's messages in a new list window, but an Open in the PyEdit component of a View or Compose window opens a simple text file and inserts its content in the message's main-text display. The latter can be used to save and resume notes in progress, or save just the main text of a mail received.

Viewing sent mails: the sentmail file

All emails you send are automatically stored by default in a saved-mail file calledsentmail.txt in the folder located at the top level of your install package. You can change this file's name and location and disable sent-mail saves altogether in files, either per account or globally; see the mail configuration base file's sentmailfilesetting for pointers. For example, you may wish to locate the sent-mail save file outside the install tree to avoid accidentally losing it on upgrades (more on upgrades ahead). Open the sent-mail save file with Open in any list window to see the mails you've sent in the GUI.

Including attachments in replies and forwards

Both Reply and Fwd in list windows automatically include and quote the original main-text part. There currently is no automatic way to include attachments from the original message, but it's easy to save and reattach any part of a message. First, open the original message with a list's View and click on the buttons of its parts that you wish to include in the reply or forward. This saves the clicked parts in the TempParts subfolder of the install'sPyMailGui-PP4E folder. Then, use the Attach button in the composewindow to reattach the saved original parts from the TempParts subfolder. A mail's parts can also be saved in and reattached from a folder of your choosing with the Split button.

Sending and viewing HTML mails

Mails composed in PyMailGUI always display and send a plain-text main part. There is no current support for creating text/HTML alternative or HTML-only emails, but you can include an HTML part attachment with a main text part that simply directs readers to open the HTML. As there are no HTML editing tools in PyMailGUI, an HTML part would be composed with other programs (e.g., MS-Word, LibreOffice, or PyEdit for the text-biased). In contrast, mails received or saved in PyMailGUI fully support both text/HTML alternative and HTML-only modes, and display their HTML parts in your web browser—on clicks for alternative mails, and along with extracted plain-text for HTML-only mails.

Saved-mail files versus server folders

Saved-mail files are a local alternative to email folders on your account's server, and allow you to partition your saved mails by categories, years, and so on. They contain text—the raw text of mails, which includes their attachments often in encoded form—but can have any name, can be stored in any folder, and may have any extension (or none). Saved-mail files emulate some of the functionality of IMAP server-account folders, but reside on your local computer only. This makes them private, and easy to access and archive offline; it also limits their visibility, though they can be propagated to other devices normally (e.g., see mergeall). Use Open in the GUI to viewthe shipped examples.

Viewing other server folders: imapfetch

As a POP client, PyMailGUI can access only the "inbox" folder at your server account; per the prior note, its local saved-mail files are designed to fill the same role as saved-mail folders at your server. You can, however, use PyMailGUI to view preexisting server email folders by first downloading their content over the IMAP interface to saved-mail files with the separate imapfetch program. Because server connection is tried only on fetches and sends, you don't need to have or configure an account to view emailssaved by either imapfetch or PyMailGUI's own Save; simply press Open in a PyMailGUI list window. IMAP download from server folders requires a one-time manual step. In exchange, though, local files are generally immune to both email-providersnooping, and ineffectual governmentoversight.

Minimizing keyboard input: password files

This hint applied to the former text-based launcher, and has been made mostly obsolete by the new GUI-based launcher in version 4.0. One part of the prior note still applies, however: you can avoid password input on each initial server connection by setting the local POP/SMTP (fetch/send) password-file paths in your files. When set to valid paths, passwords are read automatically from the files you've configured, instead of GUI popups. Password files aren't recommended on machines used by others, but are not generally any worse than allowing a web browser to remember your password in a local cookie. For more on setting this up, see Configuration.

Tips on filling in message header fields

When entering recipient email addresses in To, Cc, and other fields, be sure to quote the optional name portion if it contains special characters (for instance: "name" user@server.com). When entering _multiple_recipients, separate email addresses with a comma (for example: address1, address2, address3). The standard control/Ctrl plus C and V key combinations work to _copy and paste_text in header fields; on some platforms a right- (or two-finger-) click may paste as well. For sends: if the initial "?" character in an address field is left unchanged, no address will be used for the field; by contrast, the initial "?" in Subject will be used as your email's subject line if unchanged—be sure to fill in a valid subject.

Emojis are replaced for display 🙁 (but Unicode symbols work ☺_)_

Because _emojis_—Unicode symbols whose codepoints lie outside the BMP range—are not supported by the Tk library used by PyMailGUI, they must be replaced with a � Unicode replacement character for display in the GUI (only). You also cannot enter them in the GUI's edit fields. For more details, see the "About emojis" note in PyEdit's User Guide, available in some packages here, and onlinehere. Despite this limitation, you can still jazz-up your emails by using any of the very many Unicode symbols and language characters that fall in the BMP's U+0000..U+FFFF codepoint range, including these: ✓ ☓ ☑ ☒ ☀ ☼ ☉ ★ ☆ ☞ ☜ ☯ ⚐ ♡ ☮ 重 出 ж म ä ☺.

For both developers and upgraders, this section logs changes made in recent PyMailGUI releases, from latest to oldest. Optional reading to be sure, but most users would do well to scan the upgrading tips before installing a new PyMailGUI.

First off, to upgrade from prior releases, be sure to save and restore (or copy) the following items from your prior PyMailGUI install's folder if they have been changed since the prior install:

• Your customized files, always; you can swap this entire folder from the old to new install
• The nested textConfig.pyin folder PyMailGui-PP4E used for text-part popups, if you have edited it
• Any sent-mail and saved-mail files, if they reside in the program's install folder and you wish to save them On the last of these: the sent-mail file does reside in your install package's folder by default as described earlier, and other saved-mail files are located in whatever folder you chose in the GUI when you saved them.

If you install a new version to a different folder, you can simply copy the items listed above from old install to new. If you install to the same folder, though, these items will be overwritten with new versions if you don't save and restore. Upgraders beware!

Per the archives, the last book's version of this program was 3.0, published in 2010 (prior book versions appeared in 2006 and 2001), and the first standalone (post-book) version was released late in 2015. Starting in October, 2016, version number 3.1 is used to denote the initial standalone release, and other 3.X releases have been numbered accordingly below. As of 2017's release 4.0, changes are marked in code by version number (e.g., "[4.0]") instead of abbreviated release dates, but this was not retroactively applied to 3.1+ changes.

Version 4 Changes

[4.1] Jun-2022: Rerelease of source code and macos app to add Message-ID

PyMailGUI's source-code and macos-app packages (only) were updated and republished in June 2022, to incorporate the following tactical changes necessitated by recent evolution in email practice:

1. Message-Id: a Message-ID header is now added to all sent mails by the PyMailGUI client, because some servers now require one, and not all SMTP servers add one. In particular, Gmail has been seen to bounce some emails without the ID, and some GoDaddy email servers do not add the ID automatically. This header is optional per spec, but is no longer treated as such in some widespread implementations. Alas, monopolies can impose de facto standards.
2. Reply-To: more clearly per spec, replies now prefill To with the received mail'sReply-To header if present, instead of From. Reply-To was formerly ignored, but some sites use it to override From (e.g., to route replies to the party who requested an online-signing, instead of the signing site that sent the request).
3. In-Reply-To, References: though more optional and irrelevant in all contexts tested,In-Reply-To and References reply headers are now added to sends with the sender's Message-ID, when one is present. Some clients may use these for threading. Nit: the implementation of References here is not fully per spec (just one ID is sent), but sufficed in all tests.
4. OpenSSL: the new macos app embeds a newer Python (3.8), whose updated OpenSSL is now required by some servers too. In short, some email servers have begun refusing requests from the 2017 packages' Python 3.5 for encrypted email transactions. This seems a potentially perennial maintenance issue.
5. Threading: the event-checks-per-second setting was throttled down from 20 to 5, to minimize CPU utilization when the client is dormant. CPU, and hence battery usage, was significant on macos before this change. Other platforms may see less improvement. See queueChecksPerSecondin this file for the code.

This is a limited release. Due to backward-incompatible changes in the PyInstaller build tool, the Windows and Linux executables were not updated for this release, and do not include its changes. For these two platforms, the new source-code package and a recent Python (e.g., 3.8+) are recommended over the current executables; see above for source-code usage info.

For more details on the changes applied in this release, search for "[4.1]" in ListWindows.py,ViewWindows.py, and other code files. For pointers on upgrading to this release, seeabove.

[4.0.1] Aug-2017: Rerelease of macos app to fix broken-pipe error

This minor patch release applies to Mac app users only. Its sole change was a fix for a rare broken-pipe error that could occur only in the Mac app distribution of this program. For details on the issue and fix, please see this web page. Only the Mac app and source code packages were rereleased as 4.0.1, not the Windows or Linux executables. The source-code package was updated to include the app fix as an example for developers (see "[4.0.1]"), but the fix is irrelevant to both source code and other platforms. Users of the 4.0 Mac app are encouraged to upgrade to this new release.

[4.0] Jun-2017: New GUI launcher, macos port, new configs model, and more

This was a colossal release with too many features to document here. Among the most notable, with major items near the top:

1. A new GUI launcher and mail configurations folder better support multiple email accounts
2. The program was ported to have full functionality on macos (in addition to Windows and Linux)
3. New Mac app and Windows and Linux executables are now available (in addition to source code)
4. Unicode characters outside Tk's BMP range are now replaced everywhere instead of causing errors
5. An account's username is now displayed in its window's title (not just the server name)
6. There are new configurable GUI items in MailConfigs, including view-window header fonts
7. Password popups are posted on their parent on Linux so they are not hidden
8. Part windows are no longer silently closed with a view-window parent
9. There are more intelligent checks for unsaved text edits on window and program closes
10. A new MailConfigs file setting, splitOpensAll, suppresses part auto-opens on Split
11. The set of clickable part (attachment) filename extensions is now user-configurable
12. This document was revised enough to qualify as a full rewrite

And so on; again, search for "[4.0]" in the source-code files for full details.

Version 3 Changes

[3.6] May-27-2016: increase SMTP (send) timeouts, Python 3.5+ change

Python 3.5 changed the way that timeouts are applied to mail send operations. Its smtplib module's server.sendmail()uses Python's socket.sendall() system call to send full mail content. Formerly, the latter applied a timeout value to each partial data transfer it performed during a call. As of 3.5, a timeout value is now applied instead to the full duration of the call, as documented here andhere. This subtly changes the meaning of timeout values—they now always impose a maximum on the total time to send an email's full content.

Both for this Python change and general usage, PyMailGUI's default SMTP timeout was increased from 20 to 120 seconds to better accommodate large emails sent on slow SMTP servers, and was moved to the main (base) mailconfig.py file for easy adjustment. In contrast to smtplib's single-call scheme, Python's poplib module used for fetches reads mails line by line manually, and is thus less sensitive to timeout values, and immune to 3.5 changes. PyMailGUI's default POP timeout was nevertheless also increased for both symmetry and future-proofing.

Search for "May2016" in code here and herefor changes applied. Timeouts are crucial in PyMailGUI; without them, the program can't be closed in the GUI if a server transaction hangs, as originally described here.

[3.5] Mar-26-2016: fix for launcher error message when > 1 "_" in filenames

[This fix has been made fully moot by the new GUI launcher in 4.0; it's historical only.] Repackaged with a trivial fix for a minor launcher buglet: on invalid account name input, the error message giving valid account-name choices included bogus strings if > 1 "_" appeared in any account configuration filename. Fixed by splitting on just 1 (first) "_", via a second argument to str.split(). Also revised this document, added a console screenshot, and added top-level example go-one.py for minimizing keyboard input on launches (defunct).

[3.4] Dec-22-2015: password files and prompts

This release adds revamped password input code which reinstates local POP (fetch) password files, described in the new usage note earlier. This feature wasn't formerly available in the GUI due to the special handling of password prompts for thread safety. Local SMTP (send) password files also work, as before. Also new: when passwords are not in files, the GUI now never asks for them after the first successful load or send, as they are valid thereafter (they were formerly reinput after server errors). Search for "Dec2015" to see code changes and new implementation notes.

[3.3] Dec-20-2015: display and help configs, Linux icons, launcher upgrades

This release adds new color configurations for the help bar and view action buttons, as captured here and here; expanded help content and actions, with three selectable displays; support for Linux app-bar icons; and more robust launcher code (now superseded by 4.0's GUI launcher code). See "Dec2015" in the code for changes made; all are only minor deviations from the original book code.

[3.2] Dec-15-2015: SSL server modes support

This release now has support for using SSL and TLS/SSL encrypted modes when communicating with your POP (fetch) and SMPT (send) email servers. SSL and its TLS extension make email transmissions more secure. To enable this, the program's configuration settings now include optional switches to turn on SSL modes, and accept port numbers at the end of server-name strings following a ":" (ports may vary per server, especially for SSL). This support is not present in the book's version of the code, but is a common expectation today. While some servers still don't implement SSL (e.g., one of the author's accounts on Earthlink), some require it (e.g., Gmail), and others generally recommend it (e.g., Godaddy).

You email provider will have the details on your server account's TLS/SSL story. For SSL configuration examples in the folder, see the self-contained Gmail file, as well as the otherSSL file examples. For all changes made in this revision, see the announcement, and search for "Dec2015" in the code here and here. Hint: the PyEdit component's Search=>Grep in View windows can be used to search the full source-code tree.

[3.1] 2011-2015: Post-book changes through standalone release

For additional changes adopted by PyMailGUI between the hosting book's publication and the original release of this standalone version, see also this pagefor changes necessitated by recent Python releases, and this listfor older PyMailGUI modifications.

[3.0] 2010: Book-based version

This version had much of the current functionality of the latest, and was included with and documented by the book PP4Epublished in December 2010 (really, January 2011, but the publisher munged the date, and the program was finalized months before publication).

Older Versions and Future Ideas

Prior to its 2015 general release, this program appeared in more-limited forms in books published in 2010, 2006, and 2001 (and copyrighted by the author of the latest release). In brief, the first version was text-messages only; the second added MIME attachments; and the third implemented Unicode and included much of the functionality available in the current standalone release.

Despite its broad usability, there is still ample room for further enhancements in PyMailGUI (e.g., minimizing the help bar, using sortable tables for list windows, popup placement, resolving some thread starvation slowdowns, address books, spelling checkers, and HTML editing). These ideas are open ended, but limited by the dual underlying goals of retaining an easy-to-use interface, and keeping this program similar to its original version in the book it came from. As usual, the code is yours to change as you wish.

Because much of this program is fully described in the book that serves as its host, we'll defer to other resources for additional details here. Please refer to the following for more information:

• The screenshots folder here for example use cases
• PyMailGUI's original, simpler, and perhaps more detailed in-program help document, available here
• The book Programming Python, 4th Edition(PP4E), where this program is developed, documented, and demonstrated

Depending on your configuration file settings, the top-of-window bar in the program's main server list window may also open the second of the above—in addition to the document you have just finished reading.

If you like this program, you may also be interested in these other productivity tools brought to you by the makers of PyMailGUI:

You can find these and other free software packages at theprograms site.