Mail

Configuration

Anti-abuse alerts

The app can write alerts to the logs when users send messages to a high number of recipients or sends a high number of messages for a short period of time. These events might indicate that the account is abused for sending spam messages.

To enable anti-abuse alerts, you’ll have to set a few configuration options via occ .

# Turn alerts on
occ config:app:set mail abuse_detection --value=on
# Turn alerts off
occ config:app:set mail abuse_detection --value=off

# Alert when 50 or more recipients are used for one single message
occ config:app:set mail abuse_number_of_recipients_per_message_threshold --value=50

# Alerts can be configured for three intervals: 15m, 1h and 1d
# Alert when more than 10 messages are sent in 15 minutes
occ config:app:set mail abuse_number_of_messages_per_15m --value=10
# Alert when more than 30 messages are sent in one hour
occ config:app:set mail abuse_number_of_messages_per_1h --value=30
# Alert when more than 100 messages are sent in one day
occ config:app:set mail abuse_number_of_messages_per_1d --value=100

Attachment size limit

Admins can prevent users from attaching large attachments to their emails. Users will be asked to use link shares instead.

'app.mail.attachment-size-limit' => 3*1024*1024,

The unit is bytes. The example about with limit to 3MB attachments. The default is 0 bytes which means no upload limit.

Background sync interval

Configure how often Mail keeps users’ mailboxes updated in the background in seconds. Defaults to 3600, minimum 300.

'app.mail.background-sync-interval' => 7200,

Disable TLS verification for IMAP/SMTP

Turn off TLS verification for IMAP/SMTP. This happens globally for all accounts and is only needed in edge cases like with email servers that have a self-signed certificate.

'app.mail.verify-tls-peer' => false

Google OAuth

This app can allow users to connect their Google accounts with OAuth. This makes it possible to use accounts without 2FA or app password.

1. Create authorization credentials. You will receive a client ID and a client secret.

2. Open the Nextcloud settings page. Navigate to Groupware and scroll down to Gmail integration. Enter and save the client ID and client secret.

Local IMAP and SMTP servers

By default, Nextcloud does not allow local hostnames and IP addresses as remote servers. This includes IMAP, SMTP and Sieve servers like localhost, mx.local and 10.0.0.3. This check can be disabled with via config/config.php.

'allow_local_remote_servers' => true,

Timeouts

Depending on your mail host, it may be necessary to increase your IMAP and/or SMTP timeout threshold. Currently IMAP defaults to 5 seconds and SMTP defaults to 20 seconds. They can be changed as follows:

IMAP timeout

'app.mail.imap.timeout' => 5

SMTP timeout

'app.mail.smtp.timeout' => 20

Sieve timeout

'app.mail.sieve.timeout' => 5

Use php-mail for sending mail

Warning

Support for using php-mail was removed in version 4.4 of the mail app!

You can use the php-mail function to send mails. This is needed for some web hosters (1&1 (1und1)).

'app.mail.transport' => 'php-mail'

Account delegation

The Mail app supports account delegation if the delegation is handled by the mail server. That means the mail server has to accept emails sent from an alias address.

In mailcow, for example, the setting is called Also allowed to send as user.

Warning

Unless paired with shared Sent mailboxes or handled otherwise by the mail server, sent messages will be stored in the sender’s personal Sent mailbox.

Snooze and scheduled sending

Note

If AJAX is selected for cron job execution in the admin settings, the snooze feature and scheduled sending are deactivated because of unreliable execution.

XOAUTH2 Authentication with Microsoft Azure AD

Added in version 3.0.0.

The Mail app supports XOAUTH2 authentication with hosted Microsoft Outlook accounts. An app has to be registered in the Microsoft Azure web interface and its credentials have to be supplied to the Nextcloud instance. You can find relevant settings in the Groupware section of the admin settings.

Step 1: Open the Azure AD Dashboard

Visit the Azure portal and navigate to the Azure AD dashboard.

Step 2: Create a new app registration

Chose a name, allow organizational and personal Microsoft accounts. Configure a web app and copy the redirect URI from the groupware settings of your Nextcloud instance. Have a look at step 8 on where to find the redirect URI. Finally, click on register to proceed.

Step 3: Copy the client ID

This ID will be needed later for the Nextcloud settings.

Step 4: Create a new client secret

Chose a descriptive name for the secret and set the an appropriate expiration date. Click on add to create the secret.

Step 5: Copy the client secret

Copy the client secret manually or by clicking on the copy button. You can find it in the value column. The secret will also be needed later for the Nextcloud settings.

Step 6: Configure Nextcloud

Open the groupware settings in the Nextcloud admin settings and fill in the client ID and client secret. Leave the tenant ID as is (common). You can also find the redirect URI here. Click on save to proceed.

Warning

Using a custom tenant ID is not covered by this guide. Only configure it if you are an expert and changed the supported account types in step 2.

Step 7: Connect Microsoft Outlook accounts

Congratulations! You are now able to use hosted Microsoft Outlook accounts in the Mail app. Use your Microsoft account email and any password when adding your account. The password will be discarded and you will be prompted with a Microsoft consent popup to log in to your account.

Generic OpenID Connect (XOAUTH2) integration

Added in version 6.0.

In addition to the built-in Google and Microsoft integrations, the Mail app can authenticate individual mail accounts over XOAUTH2 against any OpenID Connect provider, for example Keycloak, Authentik or Stalwart. An administrator registers one or more providers, each matched to accounts by the user’s email domain.

Step 1: Register an OAuth client with your identity provider

Create a confidential (web) OAuth client with your identity provider and authorize the redirect URL shown in the provider form, https://<your-nextcloud>/index.php/apps/mail/integration/oidc-auth. Grant it the scopes needed to issue mail and refresh tokens (openid email offline_access by default), and make sure the access tokens it issues are accepted by your IMAP/SMTP server for XOAUTH2.

Step 2: Configure the provider in Nextcloud

Open the groupware admin settings and find OpenID Connect integration. Click Add OIDC provider and fill in:

• Display name – a free-text label.

• Email domain – accounts whose address is in this domain use this provider.

• IMAP and SMTP – host, port and encryption for the mail servers. The two may differ.

• Discovery endpoint – the provider’s .well-known/openid-configuration URL. Providers that don’t publish one can instead have their authorization, token and (optional) introspection endpoints entered manually.

• Client ID / Client secret – the credentials of the OAuth client from step 1. The secret is stored encrypted.

• Scopes – defaults to openid email offline_access.

Note

Matching is by email domain, case-insensitive but otherwise exact. There can only be one provider per domain.

Step 3: Users add their account

When a user adds a mail account whose address is in a configured domain, Mail pre-fills the mail servers and opens a consent popup at the identity provider instead of asking for a password. No password is stored for the account.

Refresh tokens keep the account syncing in the background. If a refresh token is revoked or expires without being renewed, the affected account is flagged and the user is asked to reconnect through the same consent popup the next time they open Mail.

Mailbox Share

Users can share mailboxes with each other. So far, there is no UI for users to change the ACL in the Mail app, but if you want to use it, you need to enable it on the IMAP sever and configure the shares there.

User Interface Preference Defaults

Added in version 5.2: Nextcloud 30 or newer

The Mail app allows administrators to set default user interface preferences for all users, these preferences can be changed by the user afterwards. This can be useful to ensure a consistent experience across the application.

LLM Processing

The Mail app can optionally use large language models to process emails and offer assistance features like thread summaries, smart replies, event agendas and follow-up reminders.

Note

The supported languages depend on the used large language model.

Note

A fast text processing integration like https://apps.nextcloud.com/apps/integration_openai is required for best results.

The feature can be enabled in the Mail administration settings.

Administration settings > Groupware > Mail app > Enable text processing through LLMs

Thread Summary

Changed in version 3.6.0: Nextcloud 26 or newer This configuration option was merged into LLM Processing

The mail app supports summarizing message threads that contain 3 or more messages.

Warning

A text generation AI integration should be already in place to enable this feature.

The feature is opt-in, it is disabled by default and can be enabled in mail administration settings.

Administration settings > Groupware > Mail app > Enable thread summary

Follow-up reminders

Added in version 4.0: Nextcloud 30 or newer

The Mail app will automatically remind users when their outgoing emails remain unanswered for multiple days. Each sent email will be analyzed by an AI to check whether a reply is expected.

The feature can be enabled through the global LLM Processing setting.

Translation

Added in version 4.2: Nextcloud 30 or newer

The mail app can optionally provide translations for messages if the translation API is enabled.

User migration

Added in version 5.13: Nextcloud 32 or newer

Important

The User Migration App must be installed and enabled on both instances.

To migrate user data from one Nextcloud instance to another, use the User Migration App via the occ user:export or occ user:import command line tool.

The Mail app can migrate the following data:

• Manually added mail accounts and their respective account settings (e.g., display name, signature, quick actions, …)

• Configured internal addresses

• Configured trusted senders

• S/MIME certificates and private keys

• General app settings like the order of mail accounts

Note

Import/Export of JMAP accounts is not supported at the moment and will be added in a later version.

Note

Provisioned mail accounts are not migrated, as they are expected to be re-provisioned on the new instance.

Note

The User Migration App is not a backup solution, as existing data is not being removed before the import process.

See the User Migration App on the Nextcloud App Store for more information.