docs: Fetchmail revisions
This commit is contained in:
Brennan Kinney
GitHub
parent
e7727ffe75
commit
eda55af69a
|
|
@ -2,7 +2,7 @@
|
|||
title: 'Advanced | Email Gathering with Fetchmail'
|
||||
---
|
||||
|
||||
To enable the [fetchmail][fetchmail-website] service to retrieve e-mails set the environment variable `ENABLE_FETCHMAIL` to `1`. Your `compose.yaml` file should look like following snippet:
|
||||
To enable the [fetchmail][fetchmail-website] service to retrieve e-mails, set the environment variable `ENABLE_FETCHMAIL` to `1`. Your `compose.yaml` file should look like following snippet:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
|
|
@ -26,56 +26,87 @@ Generate a file called `fetchmail.cf` and place it in the `docker-data/dms/confi
|
|||
|
||||
A detailed description of the configuration options can be found in the [online version of the manual page][fetchmail-docs].
|
||||
|
||||
!!! example "IMAP Configuration"
|
||||
!!! example "Basic Configuration"
|
||||
|
||||
Configure fetchmail to connect to the remote mailservice to retrieve mail:
|
||||
|
||||
```fetchmailrc
|
||||
poll 'imap.gmail.com' proto imap
|
||||
user 'username'
|
||||
pass 'secret'
|
||||
is 'user1@example.com'
|
||||
ssl
|
||||
poll 'mail.remote-mailservice.com'
|
||||
proto imap
|
||||
user 'remote-user'
|
||||
pass 'secret'
|
||||
is 'dms-user@example.com'
|
||||
```
|
||||
|
||||
!!! example "POP3 Configuration"
|
||||
- `poll` sets the remote mail server to connect to retrieve mail from.
|
||||
- `proto` lets you connect via IMAP or POP3.
|
||||
- `user` and `pass` provide the login credentials for the remote mail service account to access.
|
||||
- `is` configures where the fetched mail will be sent to (_eg: your local DMS account in `docker-data/dms/config/postfix-accounts.cf`_).
|
||||
|
||||
```fetchmailrc
|
||||
poll 'pop3.gmail.com' proto pop3
|
||||
user 'username'
|
||||
pass 'secret'
|
||||
is 'user2@example.com'
|
||||
ssl
|
||||
```
|
||||
!!! warning "`proto imap` will still delete remote mail once fetched"
|
||||
|
||||
!!! caution
|
||||
This is due to a separate default setting `no keep`. Adding the setting `keep` to your config on a new line will prevent deleting the remote copy.
|
||||
|
||||
Don’t forget the last line! (_eg: `is 'user1@example.com'`_). After `is`, you have to specify an email address from the configuration file: `docker-data/dms/config/postfix-accounts.cf`.
|
||||
!!! abstract "Fetchmail docs"
|
||||
|
||||
!!! tip
|
||||
The `fetchmail.cf` config has many more settings you can set as detailed in the [fetchmail docs (section "The run control file")][fetchmail-docs-config].
|
||||
|
||||
More details how to configure fetchmail can be found in the [fetchmail man page in the chapter “The run control file”][fetchmail-docs-run].
|
||||
Each line from the example above is documented at the section in a table within the "keyword" column.
|
||||
|
||||
---
|
||||
|
||||
!!! example "Multiple users and remote servers"
|
||||
|
||||
The official docs [config examples][fetchmail-config-examples] show a common convention to indent settings on subsequent lines for a visual grouping per server. The config file also allows for some optional "noise" keywords, and `#` for adding comments.
|
||||
|
||||
=== "Minimal syntax"
|
||||
|
||||
```fetchmailrc
|
||||
# Retrieve mail for users `john.doe` and `jane.doe` via IMAP at this remote mail server:
|
||||
poll 'mail.remote-mailservice.com' proto imap
|
||||
user 'john.doe' pass 'secret' is 'johnny@example.com'
|
||||
user 'jane.doe' pass 'secret' is 'jane@example.com'
|
||||
|
||||
# Also retrieve mail from this mail server (but via POP3):
|
||||
poll 'mail.somewhere-else.com' proto pop3 user 'john.doe@somewhere-else.com' pass 'secret' is 'johnny@example.com'
|
||||
```
|
||||
|
||||
=== "With optional syntax"
|
||||
|
||||
```fetchmailrc
|
||||
# Retrieve mail for users `john.doe` and `jane.doe` via IMAP at this remote mail server:
|
||||
poll 'mail.remote-mailservice.com' with proto imap wants:
|
||||
user 'john.doe' with pass 'secret', is 'johnny@example.com' here
|
||||
user 'jane.doe' with pass 'secret', is 'jane@example.com' here
|
||||
|
||||
# Also retrieve mail from this mail server (but via POP3).
|
||||
# Notice how the remote username includes a full email address,
|
||||
# Some mail servers like DMS use the full email address as the username:
|
||||
poll 'mail.somewhere-else.com' with proto pop3 wants:
|
||||
user 'john.doe@somewhere-else.com' with pass 'secret', is 'johnny@example.com' here
|
||||
```
|
||||
|
||||
### Polling Interval
|
||||
|
||||
By default the fetchmail service searches every 5 minutes for new mails on your external mail accounts. You can override this default value by changing the ENV variable `FETCHMAIL_POLL`:
|
||||
By default the fetchmail service will check for new mail at your external mail accounts every 5 minutes.
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- FETCHMAIL_POLL=60
|
||||
```
|
||||
!!! example "Override default polling interval with the `FETCHMAIL_POLL` ENV"
|
||||
|
||||
You must specify a numeric argument which is a polling interval in seconds. The example above polls every minute for new mails.
|
||||
```yaml
|
||||
environment:
|
||||
# The fetchmail polling interval in seconds:
|
||||
FETCHMAIL_POLL: 60
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
To debug your `fetchmail.cf` configuration run this command:
|
||||
To debug your `fetchmail.cf` configuration run this `setup debug` command:
|
||||
|
||||
```sh
|
||||
./setup.sh debug fetchmail
|
||||
docker exec -it dms-container-name setup debug fetchmail
|
||||
```
|
||||
|
||||
For more information about the configuration script `setup.sh` [read the corresponding docs][docs-setup].
|
||||
|
||||
!!! example "Sample output of `setup debug fetchmail`"
|
||||
??? example "Sample output of `setup debug fetchmail`"
|
||||
|
||||
```log
|
||||
fetchmail: 6.3.26 querying outlook.office365.com (protocol POP3) at Mon Aug 29 22:11:09 2016: poll started
|
||||
|
|
@ -119,10 +150,10 @@ For more information about the configuration script `setup.sh` [read the corresp
|
|||
|
||||
!!! tip "Troubleshoot with this reference `compose.yaml`"
|
||||
|
||||
[Here is a minimal `compose.yaml` example][fetchmail-compose-example] that runs two instances of DMS locally, with one configured with `fetchmail.cf`.
|
||||
[A minimal `compose.yaml` example][fetchmail-compose-example] demonstrates how to run two instances of DMS locally, with one instance configured with `fetchmail.cf` and the other to simulate a remote mail server to fetch from.
|
||||
|
||||
[docs-setup]: ../../config/setup.sh.md
|
||||
[fetchmail-website]: https://www.fetchmail.info
|
||||
[fetchmail-docs]: https://www.fetchmail.info/fetchmail-man.html
|
||||
[fetchmail-docs-run]: https://www.fetchmail.info/fetchmail-man.html#31
|
||||
[fetchmail-docs-config]: https://www.fetchmail.info/fetchmail-man.html#the-run-control-file
|
||||
[fetchmail-config-examples]: https://www.fetchmail.info/fetchmail-man.html#configuration-examples
|
||||
[fetchmail-compose-example]: https://github.com/orgs/docker-mailserver/discussions/3994#discussioncomment-9290570
|
||||
|
|
|
|||
Loading…
Reference in New Issue