Email

Posit Package Manager uses the [Mail] and [SMTP] sections to send email. No feature sends email until you turn on email for that feature. The documentation for each feature that sends email tells you how to turn it on. For example, see package request email notifications.

Choose a provider

Set Mail.Provider to one of these values:

Provider What Package Manager does
none Sends no email. This is the default.
smtp Sends email through the SMTP server in the [SMTP] section.
sendmail Sends email through the local /usr/sbin/sendmail program.
file For tests only. Writes each message as an .eml file under the mail directory in Server.DataDir, and sends nothing.

For every provider other than none, set Mail.SenderEmail to one email address, with no display name. If Mail.SenderEmail is blank, is not one email address, or has a display name, Package Manager does not start. To set the display name, use Mail.SenderDisplayName.

Warning

Package Manager can hold email that it has not sent yet. If you set Mail.Provider to none at that time, Package Manager drops that email. It does not send it later.

Configure SMTP

This example sends email through an SMTP server on port 587 with STARTTLS and a user name and password:

/etc/rstudio-pm/rstudio-pm.gcfg
[Mail]
Provider = smtp
SenderEmail = package-manager@example.com

[SMTP]
Host = smtp.example.com
Port = 587
StartTLS = required
User = package-manager
Password = <encrypted-password>

SMTP.StartTLS has three values:

  • required is the default. Package Manager uses STARTTLS. If the server does not offer STARTTLS, the delivery fails.
  • detect: when the server offers STARTTLS, Package Manager uses it.
  • never does not use STARTTLS.

For a server that uses implicit TLS, usually on port 465, set SMTP.SSL = true and SMTP.Port = 465.

If you set SMTP.User, also set SMTP.StartTLS = required or SMTP.SSL = true. Package Manager does not send a password over a connection that can be unencrypted. Without one of these values, Package Manager does not start.

SMTP.Password is an encrypted string. Plain text values work, but we recommend an encrypted value. To encrypt the password, use the rspm encrypt command. See Configuration Encryption.

The [SMTP] keys have the same names as the [SMTP] keys of Posit Connect. You can copy an [SMTP] section from a Connect configuration file. If the password in Connect is encrypted, encrypt it again with rspm encrypt. If the section sets SMTP.User, make sure that SMTP.StartTLS is always or required, or that SMTP.SSL is true. Without one of these values, Package Manager does not start.

Configure sendmail

To send email through a local mail transfer agent, set Mail.Provider = sendmail. Package Manager runs /usr/sbin/sendmail. The [SMTP] section has no effect with this provider.

Send a test email

Use the test email route to make sure that your configuration works. The route sends one message at once. It does not wait for a queue, so the response tells you if the delivery worked.

Advanced

The route requires an API token with the global:admin scope. See API Token Scopes and Creating API Tokens.

Terminal
curl -X POST \
  -H "Authorization: Bearer ${PACKAGEMANAGER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"recipient": "you@example.com"}' \
  "${PACKAGEMANAGER_ADDRESS}/__api__/config/mail/test"

The response names the provider. With the file provider, it also gives the path of the file:

{"provider": "smtp"}

The route can return these errors:

  • 400: the request has no JSON body or a body that is not valid, Mail.Provider is none, or the recipient is not a valid email address.
  • 401: the request has no API token, or the token is not valid.
  • 403: the token does not have the global:admin scope.
  • 502: the delivery failed. The response gives the error from the mail server.

Delivery and retries

Package Manager keeps unsent email in its database. In a cluster, one node sends all email. Give every node the same [Mail] and [SMTP] keys.

If a delivery fails for a temporary reason, Package Manager tries again later. The wait starts at two minutes and doubles after each attempt, up to one hour. After Mail.MaxAttempts attempts, Package Manager marks the message as failed. If the mail server rejects a message permanently, Package Manager marks it as failed at once.

If Package Manager does not send a message within Mail.SentRetention, it also marks the message as failed.

Retention

Once each hour, Package Manager removes old email records:

  • Mail.SentRetention sets how long Package Manager keeps the record of a sent message. The default is 30 days (720h). The file provider removes its .eml files after the same time.
  • Mail.FailedRetention sets how long Package Manager keeps the record of a failed message. The default is 30 days (720h).

Reload the configuration

All the [Mail] and [SMTP] keys are reloadable. After you change them, send a hangup (HUP) signal to Package Manager. See Stopping and Starting. If a new value is not valid, Package Manager keeps the previous configuration and logs an error. For example, a Mail.SenderEmail with a display name is not valid.

For every [Mail] and [SMTP] key, see the Mail and SMTP sections of the configuration appendix.

Back to top