Add selected Mail to TaskPaper 3 project at given filepath

A custom Keyboard Maestro plugin, for Sierra macOS onwards, which adds a KM Action for sending selected Mail (with hyperlinks back to Mail) to:

  1. A specified TaskPaper 3 project, in
  2. a .taskpaper file at a given filepath (TaskPaper 3 is not launched, and does not have to be running for the action to work )

Add selected Mail to TaskPaper 3 (251.5 KB)

Custom Keyboard Maestro Plug-in

(c) 2017 Robin Trew


  • Add selected Mail to TaskPaper 3 project


  • 0.4


Any items selected in Apple Mail are added to a named project in a specified
TaskPaper 3 file. The text format of the
TaskPaper entry is specified by a template which can contain any or all of
10 string, date and url fields.

The TaskPaper 3 application does not have to
be running, and is not launched by this Keyboard Maestro action.


  • The file path to the TaskPaper 3 file can
    include a ~/ abbreviation of the user's home path, and should include
    the .taskpaper file extension

  • A checkbox enables automated creation of a new file, if no file is found
    at the given path.

  • In the item-format text field, the field names should be given in angle

    • <fromName> name of sender (uses email where name string empty)
    • <fromEmail> email address of sender
    • <subject> email subject as displayed in Mail
    • <url> hyperlink back to the Mail item
    • <received> an abbreviated ISO 8601 date time string
    • <sent> an abbreviated ISO 8601 date time string
    • <now> an abbreviated ISO 8601 date time string
    • <box> the name of the mailbox containing the email
    • <toName> name of first recipient, if any (for sent mail)
    • <toEmail> name of first recipient, if any (for sent mail)
  • The 'New messages at:' option determines whether items will be added at the
    top or the bottom of the specified TaskPaper 3 project

  • The plugin avoids creating duplicate entries for the same email
    (by checking the urls already present in the TaskPaper 3 project)

  • Any Keyboard Maestro text tokens will be expanded in the File path,
    Project name, and item-format fields of the plugin.


  • This plugin has been so far tested on macOS Sierra, with Keyboard Maestro 8
  • It uses the 700K Birch Outline library (Copyright (c) 2016 Jesse Grosjean) to
    parse and update a TaskPaper 3 file without opening the application directly.


  1. If updating a previous version of the action, first manually remove the
    previous copy from the custom actions folder at:
    • ~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Actions
  • Drag the .zip file onto the Keyboard Maestro icon in the OS X toolbar.


  1. In macro-editing mode, click the green New Action button, select the
    Third Party Plugins smart folder in the left hand panel of the Actions List
    and choose the "Add selected Mail to TaskPaper 3 project"
  2. Adjust the settings of the custom action, choosing the file path,
    project name, and TaskPaper 3 item format that you want.
  3. Test the macro. If notifications are enabled on your macOS system, or you
    have changed 'Display results briefly' to 'Display in a Window' at the
    bottom of the custom plugin, you will see a brief summary of the result.


The plugin uses the excellent Birch Outline library,
which is Copyright (c) 2016 Jesse Grosjean.
The Keyboard Maestro custom plugin is Copyright (c) 2017 Robin Trew,
and was created with the help of specifications and sponsorship provided by
Jim Krenz.
Icon by Jim Krenz.


1 Like

Thank you yet again @ComplexPoint !

awesome! wonder how hard or if it is possible to do this with Airmail?

Looks promising, I think. Iā€™m not an Airmail user myself, but glancing at its scripting dictionary I see that it does provide:

  1. List of selected messages
  2. URLs back to particular messages
  3. Basic fields for each message: (name, sender, subject, addressees)

The only gap looks like the datetime of the email, though of course the date-time of the script-run is still available, and clicking back to the message through the URL lets you read the original date.