Skip to content

Set up email notifications ​

This guide connects the kit-notify-email kit to an SMTP server. After it, Tara, Ryoma, or Bandum can send alerts and review events by email to a fixed list and to the people concerned. It takes about ten minutes, and there is no token to renew.

About the picture

The figures are illustrations that show where to click. Google and the Portal change their screens from time to time, so the real screen may look a little different. The names of the buttons stay the same.

Who this is for ​

  • An administrator who installs notification kits on a server (see Notifications).
  • Whoever manages the mail account or relay that sends the alerts.

Before you start ​

  • An SMTP server and an account that may send mail: server name, port, account name, and password.
  • A sender address (from) that the server accepts.
  • The ph command on your machine, to test the kit before you touch the server.
  • The kit version and its sha256 from the kit-notify-email resource page on Tara. Use them as kit-notify-email@<version>:<sha256>.

Choose the server ​

ServerhostportsecurityAccount and password
Gmail or Google Workspacesmtp.gmail.com587starttlsYour address, and an App password (needs 2-Step Verification)
SendGrid, or a similar transactional servicesmtp.sendgrid.net587starttlsUsername apikey, password = the API key
Internal relayYour relayIts portnone, only inside your own networkOften no sign-in: leave username empty

For Microsoft 365, SMTP AUTH with a password must be enabled for the mailbox, and Microsoft is phasing out basic authentication. Prefer a transactional service or a relay.

Use security tls with port 465 for servers that expect TLS from the first byte. The default is starttls on port 587.

1. Create an app password (Gmail) ​

Skip this step if you use another server.

  1. Turn on 2-Step Verification for the sending account at https://myaccount.google.com/security.
  2. Open https://myaccount.google.com/apppasswords.
  3. Enter a name, for example PhillipCLI, and choose Create.
  4. Copy the password that Google shows. It appears only once. Use it as the SMTP password.
Illustration, the real screen may differ slightly. Enter an app name and choose Create (1). Copy the 16-character password that Google shows (2): it is shown only once.

2. Decide the settings ​

SettingDefaultMeaning
host(required)The SMTP server
from(required)The sender address
securitystarttlsstarttls, tls, or none
port587, or 465 with tlsThe server port
usernameemptyThe sign-in account. Empty means no sign-in
recipientsemptyAddresses that always receive, separated by commas
sendToPersontrueAlso send to the person concerned. Set false to send only to recipients
helolocalhostThe name in the EHLO command

The password is not a setting. It goes in the secret variable only.

3. Test the kit with ph kit check ​

Pass the password through the PHILLIP_KIT_TOKEN variable, never as an argument. The command ph kit check takes a kit folder or name[@version], repeated --set key=value, --live, and --send <text> with optional --to.

bash
PHILLIP_KIT_TOKEN=<SMTP password> ph kit check kit-notify-email \
  --set host=smtp.gmail.com --set username=alerts@example.com --set from=alerts@example.com \
  --send "test" --to you@example.com
  • With --live, the command connects, encrypts, and signs in, and sends nothing. The result looks like smtp host:587 (starttls), from ….
  • With --send, it sends a real email to --to and to recipients.

4. Configure the service ​

Tara, Ryoma, and Bandum use the same kit. Each service has its own variable prefix. The example below is for Ryoma. Take <version> and <sha256> from the Tara resource page.

bash
RYOMA_NOTIFY_PLUGINS=kit-notify-email@<version>:<sha256>
RYOMA_NOTIFY_SECRET_KIT_NOTIFY_EMAIL=<SMTP password>
RYOMA_NOTIFY_SETTINGS={"kit-notify-email":{"host":"smtp.gmail.com","username":"alerts@example.com","from":"alerts@example.com","recipients":"pm@example.com"}}
ServiceKitsDefault settingsSecret
TaraTARA_NOTIFY_PLUGINSTARA_NOTIFY_SETTINGSTARA_NOTIFY_SECRET_KIT_NOTIFY_EMAIL
RyomaRYOMA_NOTIFY_PLUGINSRYOMA_NOTIFY_SETTINGSRYOMA_NOTIFY_SECRET_KIT_NOTIFY_EMAIL
BandumBANDUM_NOTIFY_PLUGINSBANDUM_NOTIFY_SETTINGSBANDUM_NOTIFY_SECRET_KIT_NOTIFY_EMAIL

Tara also needs TARA_NOTIFY_TOKEN, a read-only Tara token that downloads the kit package. Restart the service after you change the variables. For the other variables, see Notifications.

5. Choose the channel for each organization ​

The password stays one per kit on the server, so all organizations send through the same account. Each organization sets its own recipients.

  1. Sign in to the Portal as an owner or admin of the organization. Open the account menu, then Admin, then Notifications, then add a channel.
  2. Choose the Organization and the Plugin kit-notify-email.
  3. In Organization-specific settings, enter one name=value per line, for example recipients=pm@acme.example. Do not enter a password here: Tara rejects setting names that look like secrets.
  4. Choose the events to receive, then save.
  5. In the row's actions menu, choose Send test.
Enter recipients=… in Organization-specific settings (1), choose the events (2), then choose Save (3). Send a test from the channel row's actions menu.

You can do the same from the command line:

bash
ph tara notify set <org> kit-notify-email --set recipients=pm@acme.example --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-email

Troubleshooting ​

Error textCauseFix
settings.host (SMTP server) is missingNo hostAdd host
settings.from must be an email addressfrom is empty or not an addressUse a full address such as alerts@example.com
settings.security must be "starttls", "tls" or "none"A wrong valueUse one of the three
settings.username is set but the SMTP password is missingusername without the secretSet <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_EMAIL and restart
SMTP AUTH: 535 …Wrong account or password. For Gmail, a normal password instead of an App passwordCreate an App password, or copy the password again
<host> does not support STARTTLS (set settings.security = "tls" or "none")The server does not offer STARTTLS on this portUse security=tls with port 465, or none inside your network
could not connect to SMTP <host>:<port> (…)Wrong host or port, or a firewall blocks itCheck the address and the network route
STARTTLS with <host> failed (…)The TLS handshake failedCheck the certificate of the server and the port
the SMTP server did not respondNo answer within 20 secondsCheck the server and the route
SMTP RCPT: 550 …The server refuses a recipient or the senderFix the address, or allow the sender on the server

When there is no valid recipient, the kit sends nothing and reports no error. Check recipients first if no email arrives.

Limits ​

  • Plain text only, with a UTF-8 body.
  • Recipients are recipients plus the people concerned (unless sendToPerson is false). Addresses in a wrong format are skipped.
  • All organizations send through the same sender account, because the password is one per kit on the server.
  • Messages carry metadata and links only, never the content of work.

Further reading ​