Additional plugin usage examples and documentation

Author: simonrob

emailproxy.config

@@ -39,18 +39,20 @@ documentation = Local servers are specified as demonstrated below where, for exa
 	/etc/letsencrypt/live/mail.example.net/privkey.pem) for the server you are using the proxy with, and it will use
 	these to set up a secure connection between itself and your email client.
 
-	Experimental feature - proxy plugins:
-	- Plugins are a semi-experimental new feature that enables the use of separate scripts to modify IMAP/SMTP commands
-	when they are received from the client or server before passing through to the other side of the connection. The
-	`plugins` property is a dictionary of one or more plugins, specified in the order that they should be applied to
-	all received data, starting after authentication succeeds. Plugins are chained, so they can both edit incoming
-	messages; and, use these as triggers to initiate their own communication with the server without any need to reveal
-	this to the client (for example: client -> p1 -> p2 -> server -> p2 -> server -> p2 -> p1 -> client). Each key of
-	the `plugins` property must be the name of a plugin you want to apply (note: the plugin's filename and its main
-	class name must be identical). Each value should either be an empty dictionary if the plugin has no setup arguments;
-	or, a set of key-value pairs to match the plugin's named initialisation parameters. See the [IMAP-2995] example
-	below, which loads the IMAPIgnoreSentMessageUpload plugin with its `target_mailboxes` configured to match Gmail's
-	`Sent Mail` mailbox. For further details and documentation, see the range of sample plugins.
+	Advanced feature - proxy plugins:
+	- Plugins are an advanced feature that enable the use of separate scripts to modify IMAP/POP/SMTP commands when they
+	are received from the client or server before passing through to the other side of the connection. The `plugins`
+	property is an dictionary of one or more plugins, specified in the order that they should be applied to all received
+	data. On the client side of the connection plugins are run in the order shown; on the server side plugins are run in
+	reverse order. On the server side, plugins can be used at any point, but for security reasons plugins on the client
+	side are inserted after authentication has succeeded. Plugins are chained, so they can both edit incoming messages;
+	and, use these as triggers to initiate their own communication with the server without any need to reveal this to
+	the client (for example: client -> p1 -> p2 -> server -> p2 -> server -> p2 -> p1 -> client). Each key of the
+	`plugins` property must be the name of a plugin you want to apply (note: the plugin's filename and its main class
+	name must be identical). Each value should either be an empty dictionary if the plugin has no setup arguments; or,
+	a set of key-value pairs to match the plugin's named initialisation parameters. See the [IMAP-1994] and [IMAP-1995]
+    entries below for example plugin configurations. For further details and documentation, see the range of sample
+    plugins at https://github.com/simonrob/email-oauth2-proxy/tree/plugins/plugins.
 
 [IMAP-1993]
 server_address = outlook.office365.com
@@ -84,9 +86,23 @@ server_port = 465
 local_address = 127.0.0.1
 
 [IMAP-1994]
+server_address = outlook.office365.com
+server_port = 993
+local_address = 127.0.0.1
+plugins = {
+		'IMAPFixO365SearchQuirks': {},
+		'IMAPIgnoreSentMessageUpload': {'target_mailboxes': ['Sent Items']},
+		'IMAPLinkDestinationRevealer': {},
+		'IMAPCleanO365ATPLinks': {}
+	}
+
+[IMAP-2994]
 server_address = imap.gmail.com
 server_port = 993
-plugins = {'IMAPIgnoreSentMessageUpload': {'target_mailboxes': ['[Gmail]/Sent Mail', '[Google Mail]/Sent Mail']}}
+plugins = {
+		'IMAPIgnoreSentMessageUpload': {'target_mailboxes': ['[Google Mail]/Sent Mail', '[Gmail]/Sent Mail']},
+		'IMAPDeflateCompressionRemoteEnabler': {}
+	}
 
 
 [Account setup]
@@ -169,7 +185,7 @@ documentation = Accounts are specified using your email address as the section h
 		service account with the proxy in a publicly-accessible context is not advised. You are highly encouraged to
 		enable the proxy's secret encryption option (see `encrypt_client_secret_on_first_use` at the end of this file)
 		and consider pre-encrypting account entries. A sample pre-encryption script is provided for reference at
-		https://github.com/simonrob/email-oauth2-proxy/issues/212#issuecomment-1867557029
+		https://github.com/simonrob/email-oauth2-proxy/issues/212#issuecomment-1867557029.
 
 	Advanced account configuration:
 	- For most configurations the default `redirect_uri` value of `http://localhost` is correct, unless you have

plugins/README.md

@@ -1,6 +1,7 @@
 # Email OAuth 2.0 Proxy plugins
 Plugins are an advanced Email OAuth 2.0 Proxy feature that enable the use of separate scripts to modify IMAP/POP/SMTP commands when they are received from the client or server before passing through to the other side of the connection.
 This allows a wide range of additional capabilities or triggers to be added the proxy, as demonstrated in the examples below.
+See the [sample configuration file](../emailproxy.config#L42) for further application examples and documentation.
 
 
 ## Sample plugins