Motivation

Starting with v8.20, the Open-Xchange Server supports the transport of mails at a later time. The user is able to specify the desired time when a certain mail is supposed to be sent.

Prerequisites

In order to support sending a composed mail at a desired date, the package open-xchange-mail-scheduled needs to be installed.

Moreover, the middleware needs a credential of its own to send a mail at its due time; see Credentials for sending later.

In addition, the feature also needs to be enabled for App Suite UI through the following UI setting:

io.ox/core//features/scheduleSend = true

Configuring scheduled mail feature

• "com.openexchange.mail.scheduled.active" is the switch to turn off the feature as a whole. If set to false, the feature is not started on that node at all: it neither announces the capability nor sends due scheduled mails. Use the same value on all nodes. Defaults to true. This property is neither reloadable nor config-cascade aware; a change requires a restart.
• "com.openexchange.mail.scheduled.enabled" controls whether the feature is available for a user or context. Only effective if "com.openexchange.mail.scheduled.active" is true. Defaults to false. This property is reloadable and config-cascade aware.
• "com.openexchange.mail.scheduled.checkAndSendDueScheduledMails" controls whether a node checks for due scheduled mails and sends them. Set to false to keep nodes out of sending, e.g. to let dedicated nodes do it. Defaults to true. This property is reloadable, but not config-cascade aware.
• "com.openexchange.mail.scheduled.maxNumberOfScheduledMails" specifies the max. allowed number of scheduled mails per user. This property is reloadable and config-cascade aware.
• "com.openexchange.mail.scheduled.maxNumberOfScheduledMailsPerHour" specifies the max. allowed number of scheduled mails being sent per hour for a user. This property is reloadable and config-cascade aware.
• "com.openexchange.mail.scheduled.checkFrequencyMinutes" specifies the frequency in minutes when to check for due scheduled mails. This property is reloadable, but not config-cascade aware.
• "com.openexchange.mail.scheduled.lookAheadMinutes" specifies the look-ahead in minutes that is the extra time added to now when a scheduled mail is considered as due. This property is reloadable, but not config-cascade aware.
• "com.openexchange.mail.scheduled.lockExpiryMinutes" specifies the time in minutes when the lock marking a scheduled mail as "in processing" is considered as expired and thus may be newly acquired by another process. This property is reloadable, but not config-cascade aware.
• "com.openexchange.mail.scheduled.lockRefreshMinutes" specifies the time in minutes when the lock marking a scheduled mail as "in processing" is refreshed by lock-holding process. This property is reloadable, but not config-cascade aware.
• "com.openexchange.mail.scheduled.requireMasterAuth" controls whether the feature is offered only where the middleware has a credential of its own for sending later: master authentication, a token exchange or the offline grant (see below). Defaults to true. With false, it is offered anyway and uses the credential of the user's session, which ends with it. This property is reloadable and config-cascade aware.

Credentials for sending later

The middleware sends a scheduled mail at its due time while the user may not be logged in, so it needs a credential for the mail server of its own. It keeps one per mail in the mail credential vault, in one of three ways:

• Master authentication: the mail server accepts a master password for every user.

  com.openexchange.mail.passwordSource=global
  com.openexchange.mail.masterPassword=secret

• Token exchange (OAuth): the middleware exchanges the user's access token at the identity provider for tokens that outlive the session (Tokens from an exchange).
• Offline grant (OAuth): for identity providers without a suitable token exchange. The user allows background access once, in a popup at the identity provider, and the vault keeps those tokens for the user's scheduled and snoozed mails (Tokens from an offline grant):

  # For the OpenID Connect back-end the users log in with
  com.openexchange.oidc.offlineGrantEnabled=true

App Suite UI asks for the authorization when the middleware answers with MCRED-0014, and offers it in the security settings. For a step-by-step setup of the middleware, the identity provider and the mail server, see Background Mail Access.

Without one of the three, the feature is not offered (the capability stays off) unless "com.openexchange.mail.scheduled.requireMasterAuth" is set to false; then the middleware uses the credential of the user's session, which ends with it.

Narrowing the background credential at the mail server

With OAuth, the tokens of the token exchange or the offline grant log in to IMAP like the user's own. Dovecot can narrow them by ACL to what the job needs, if they carry a claim of their own; see Narrowing the grant's tokens at the mail server for the identity provider's and Dovecot's configuration. Sending later needs:

Anything else needs l only; snoozed mail adds lisw everywhere, to append returning mails, see Snooze Mails. So the background credential reads no mailbox but Scheduled (and Snoozed).

Sent through the offline grant, the mail is sent from the Scheduled folder where it waits: it is not moved to Drafts for sending, and the copy for Sent is appended blindly. Since the credential cannot read the folder of the mail a scheduled reply or forward refers to, that mail is not marked as answered or forwarded (the transport ends with a warning, the mail is sent). Every other credential - a token exchange's, master authentication, a session's - goes the usual way: the middleware moves the mail to Drafts for sending, as it does where the composition space service does not support sending a draft where it is. Narrowed, such a credential needs lrswite on Drafts and lrswi on Sent.