Skip to content

Commit

Permalink
Additional plugin usage examples and documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
simonrob committed Jan 30, 2024
1 parent 818936e commit 21d5b24
Show file tree
Hide file tree
Showing 2 changed files with 31 additions and 14 deletions.
44 changes: 30 additions & 14 deletions emailproxy.config
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions plugins/README.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down

0 comments on commit 21d5b24

Please sign in to comment.