Re: [MlMt] Bundle input types other than canonical
On 18 Apr 2014, at 18:28, Brett Terpstra wrote:
On 18 Apr 2014, at 9:41, Benny Kjær Nielsen wrote:
[…]
I guess that makes part of commands semi-documented. You might want
to ask about `output` types as well ;-)
Consider it asked.
Ok. As already indicated, `html` and `canonical` are going to be output
types for filtering commands, but this is not yet functional for
bundles. The default output type is `discard` and this leaves us with
the only interesting output for now: `actions`.
The `actions` output type expects a property list to be returned from
the command. Here is a simple example:
~~~
{
actions = (
{
type = moveMessage;
mailbox = archive;
}
);
}
~~~
Each action must have a type. Additional keys may be allowed/required
depending on the type. The currently available types are:
* `playSound`
`path`: Full path or a sound name if the sound can be found in a
standard sound path.
* `notify`
`formatString`: A format string (default is `“${subject}” from
“${from.name:${from.address}}”`).
`mailbox`: Mailbox identifier (click on a mailbox and do ⌘C to get
this value).
* `moveMessage`
`mailbox`: Mailbox identifier (must be an IMAP mailbox).
* `copyMessage`
`mailbox`: Mailbox identifier (must be an IMAP mailbox).
`variables`: More about this further below.
* `changeFlags`
`enable`: Array of IMAP flags/keywords, e.g., `( \\Flagged,
\\Send)`.
`disable`: Array of IMAP flags/keywords.
* `exportMessage`
`folderPath`: Simple disk path (it can also be a `file:` URL).
* `redirectMessage`
`recipient`: Redirect message to the recipient (this includes sending
the message).
* `createMessage`
`headers`: Dictionary with headers for the message.
`body`: Entire message body.
* `replyMessage` (currently always “Reply All”)
`headers`: Dictionary with headers for the message.
`body`: Reply part of message body.
* `runScript`
`scriptUUID`: The UUID of a bundle command. Note that this script can
return actions itself.
Note that commands also support an `executionMode` which can be
`singleMessage` or `multipleMessages` (default is `singleMessage`). This
determines whether the script should be executed once for each message
or once for all selected messages. (In `singleMessage` mode MailMate
tries to handle any resulting actions efficiently by merging them if
they are identical for subsets of messages. This is important for large
message selections.)
All actions allow an `ids` key which is an array of internal message ids
(integers). If needed, these can be provided to a script using the
virtual header named `#body-part-id`. This is only used internally by
MailMate now, but it might be useful for external purposes which I have
not realized yet.
The `copyMessage` action is special since it has two different
behaviors. If `variables` are *not* defined then it's a simple copy
action equivalent to ⌥-dragging a message. If `variables` are defined
then all headers and the body of the copied message are interpreted as
being format strings for which the `variables` should be used. This can
be used to create a draft message in MailMate with the purpose of using
it as a template for an external script. The external script could, for
example, handle a list of recipients for the draft message. An example
is probably needed to understand how this works. Imagine creating a
draft with values like this:
To: ${to}
Subject: A personal message to you.
Hi ${firstname},
I wanted to tell you about an extraordinary email client named
MailMate. I used it to create this very personal message.
Regards, Benny
The `actions` could then be generated by a script with output like this:
{ actions = (
{
type = copyMessage;
variables = {
to = 'Foo Bar foo...@example.com';
firstname = 'Foo';
};
},
{
type = copyMessage;
...
}
);
}
A practical example is the emails I sent to existing license owners when
doing the crowd funding campaign. Those emails were create by letting a
Ruby script generate the actions. It also used the variables to include
the existing license key of each user to make sure they did not have to
search for it if they were no longer actively using MailMate. I could
create the draft in MailMate using any feature of MailMate I'd like
(Markdown, Send Later, ...). The script generated a huge number of
emails in my drafts folder, but I could then review the result and add
(really)
Re: [MlMt] Bundle input types other than canonical
Great! Thanks for all the info.
-Brett
On 22 Apr 2014, at 6:20, Benny Kjær Nielsen wrote:
On 18 Apr 2014, at 18:28, Brett Terpstra wrote:
On 18 Apr 2014, at 9:41, Benny Kjær Nielsen wrote:
[…]
I guess that makes part of commands semi-documented. You might want
to ask about `output` types as well ;-)
Consider it asked.
Ok. As already indicated, `html` and `canonical` are going to be
output types for filtering commands, but this is not yet functional
for bundles. The default output type is `discard` and this leaves us
with the only interesting output for now: `actions`.
The `actions` output type expects a property list to be returned from
the command. Here is a simple example:
~~~
{
actions = (
{
type = moveMessage;
mailbox = archive;
}
);
}
~~~
Each action must have a type. Additional keys may be allowed/required
depending on the type. The currently available types are:
* `playSound`
`path`: Full path or a sound name if the sound can be found in a
standard sound path.
* `notify`
`formatString`: A format string (default is `“${subject}” from
“${from.name:${from.address}}”`).
`mailbox`: Mailbox identifier (click on a mailbox and do ⌘C to get
this value).
* `moveMessage`
`mailbox`: Mailbox identifier (must be an IMAP mailbox).
* `copyMessage`
`mailbox`: Mailbox identifier (must be an IMAP mailbox).
`variables`: More about this further below.
* `changeFlags`
`enable`: Array of IMAP flags/keywords, e.g., `( \\Flagged,
\\Send)`.
`disable`: Array of IMAP flags/keywords.
* `exportMessage`
`folderPath`: Simple disk path (it can also be a `file:` URL).
* `redirectMessage`
`recipient`: Redirect message to the recipient (this includes sending
the message).
* `createMessage`
`headers`: Dictionary with headers for the message.
`body`: Entire message body.
* `replyMessage` (currently always “Reply All”)
`headers`: Dictionary with headers for the message.
`body`: Reply part of message body.
* `runScript`
`scriptUUID`: The UUID of a bundle command. Note that this script can
return actions itself.
Note that commands also support an `executionMode` which can be
`singleMessage` or `multipleMessages` (default is `singleMessage`).
This determines whether the script should be executed once for each
message or once for all selected messages. (In `singleMessage` mode
MailMate tries to handle any resulting actions efficiently by merging
them if they are identical for subsets of messages. This is important
for large message selections.)
All actions allow an `ids` key which is an array of internal message
ids (integers). If needed, these can be provided to a script using the
virtual header named `#body-part-id`. This is only used internally by
MailMate now, but it might be useful for external purposes which I
have not realized yet.
The `copyMessage` action is special since it has two different
behaviors. If `variables` are *not* defined then it's a simple copy
action equivalent to ⌥-dragging a message. If `variables` are
defined then all headers and the body of the copied message are
interpreted as being format strings for which the `variables` should
be used. This can be used to create a draft message in MailMate with
the purpose of using it as a template for an external script. The
external script could, for example, handle a list of recipients for
the draft message. An example is probably needed to understand how
this works. Imagine creating a draft with values like this:
To: ${to}
Subject: A personal message to you.
Hi ${firstname},
I wanted to tell you about an extraordinary email client named
MailMate. I used it to create this very personal message.
Regards, Benny
The `actions` could then be generated by a script with output like
this:
{ actions = (
{
type = copyMessage;
variables = {
to = 'Foo Bar foo...@example.com';
firstname = 'Foo';
};
},
{
type = copyMessage;
...
}
);
}
A practical example is the emails I sent to existing license owners
when doing the crowd funding campaign. Those emails were create by
letting a Ruby script generate the actions. It also used the variables
to include the existing license key of each user to make sure they did
not have to search for it if they were no longer actively using
MailMate. I could create the draft in MailMate using any feature of
MailMate I'd like (Markdown, Send Later, ...). The script generated a
huge
Re: [MlMt] Bundle input types other than canonical
Ok, I'll play with the types listed and see if they do what I expect. I
guessed around last night and hit some of those, but wasn't seeing what
I thought I would. I'll let you know. Other answers inline.
On 18 Apr 2014, at 9:41, Benny Kjær Nielsen wrote:
On 18 Apr 2014, at 4:46, Brett Terpstra wrote:
Are there any input types available besides canonical?
Yes, the current input types are:
* none (the default)
No input
* raw
The message in its raw format. This is, for example, suitable for
exporting messages to other email-capable applications.
* decoded
MailMate decodes the body part if it is encoded using
quoted-printable/base64. This is primarily useful if sending specific
body parts to a command. For example, an image would be given to the
command in its raw (original) binary format. This is not currently
used by any of the included commands.
* canonical
Text body parts of the message are decoded, deflowed
(`format=flowed`), and converted to UTF-8 equivalent to what happens
before displaying a non-HTML message.
* html
Currently equivalent to what happens before MailMate displays a
message in its Webview which means that even a plain text message is
converted to HTML. This is probably mainly useful for display
purposes.
* selection
The currently selected text in the message view.
* formatted
Requires an additional `formatString` key/value pair for the command.
This is mainly useful for obtaining specific information from a large
set of messages.
The last one is quite powerful (and fast) if you want to retrieve data
for some kind of statistics. For example, retrieve all sender names of
all selected messages like this:
formatString = ${from.name:No name available}\n;
This is well suited for further handling, e.g., by standard UNIX
commands. For example, a top 10 of senders could be done like this:
sort -f | uniq -ic | sort --reverse --numeric-sort | head -10
If the receiving command can handle it then it's also fine to use the
`formatString` to provide multiple values:
formatString = ${from.name:No name available}\n${subject.body:No
subject available}\n;
When/If event types are expanded then it'll be possible to change how
MailMate displays messages by making, e.g., `canonical` - `canonical
or `html` - `html` filters. Filtering before generating a reply is
also going to be possible, e.g., to remove extraneous whitespace,
reflowing, or automatically cut signatures.
I guess that makes part of commands semi-documented. You might want to
ask about `output` types as well ;-)
Consider it asked.
Is there a way to force HTML to the bundle if it exists,
I'd probably need to know your use case to know whether or not
MailMate can do what you want. Using the `decoded` input type, the
main problem is that you need some way to tell MailMate to use the
HTML body part as the input for the command. This it tricky if not
impossible (depending on what you are trying to do).
What I want to do is run my own custom html2text on the output and save
it to a text file (for nvALT import purposes). The output I was getting
from canonical was already markdownified in most cases, and it seemed
that with html, there were cases where it would send nothing at all
(assumed it was because there was no html section). If decoded provides
the Content-Type boundaries, I can parse that...
Also, how does MM_SELECTED_RANGE work when the input to the command
isn't the same format as what was selected in the viewer?
In a sense it's never the same format since even a plain text message
is displayed as HTML. To provide `MM_SELECTED_RANGE`, MailMate
heuristically re-locates the selected text in the canonical text when
a command is executed. This currently does not happen for the `html`
input type.
Any chance that when there's a selection and the current view type is
HTML, it could send the raw selected HTML to the output? As in,
MM_SELECTED_TEXT instead of just a range?
-Brett
___
mailmate mailing list
mailmate@lists.freron.com
http://lists.freron.com/listinfo/mailmate
