[MlMt] Bundle input types other than canonical

[Benny Kjær Nielsen]

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 <foobar at 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) personal messages to some of them. Furthermore, it made it easy 
to send out the emails in smaller batches. (This wouldn't work well for 
100.000 emails, but in my case it was fine.)

Caveat: When I used some of the message-generating features myself (and 
no-one else has I believe) I had some crashes which I'm not sure have 
been fixed yet. Reports are naturally welcome.

> 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...

No, `decoded` does not provide `Content-Type` directly, but you could 
use environment variables to do that. For example,

	environment   = 
'MM_CONTENT_TYPE=${content-type.type:text}\nMM_CONTENT_SUBTYPE=${content-type.subtype:plain}\n';

But as noted, the real problem is probably to tell MailMate which body 
part to provide to the script.

With respect to `canonical` not being the desired data (or the Markdown 
conversion being inadequate) then I'd like to fix that by extending the 
set of input types or by improving the HTML to Markdown conversion 
(maybe we should discuss your version of `html2text` off list).

On a more general note, my goal is to provide input which takes care of 
as many of the email intricacies as possible before handing over data to 
commands or other parts of the interface. The many(!) problems 
concerning the conversion of headers and bodies to any kind of canonical 
data should be handled by MailMate to keep everything else as simple as 
possible. In other words, canonicalization should be my side of the 
fence.

>>> 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?

To be consistent I think it should be a new input type: 
`html_selection`. And for the `html` input type `MM_SELECTED_RANGE` 
should be made available as it is for `canonical` (I'm not sure how easy 
the latter would be).

-- 
Benny
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freron.com/pipermail/mailmate/attachments/20140422/333f1b29/attachment.html>