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
phcommand on your machine, to test the kit before you touch the server. - The kit version and its sha256 from the
kit-notify-emailresource page on Tara. Use them askit-notify-email@<version>:<sha256>.
Choose the server
| Server | host | port | security | Account and password |
|---|---|---|---|---|
| Gmail or Google Workspace | smtp.gmail.com | 587 | starttls | Your address, and an App password (needs 2-Step Verification) |
| SendGrid, or a similar transactional service | smtp.sendgrid.net | 587 | starttls | Username apikey, password = the API key |
| Internal relay | Your relay | Its port | none, only inside your own network | Often 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.
- Turn on 2-Step Verification for the sending account at
https://myaccount.google.com/security. - Open
https://myaccount.google.com/apppasswords. - Enter a name, for example
PhillipCLI, and choose Create. - Copy the password that Google shows. It appears only once. Use it as the SMTP password.
2. Decide the settings
| Setting | Default | Meaning |
|---|---|---|
host | (required) | The SMTP server |
from | (required) | The sender address |
security | starttls | starttls, tls, or none |
port | 587, or 465 with tls | The server port |
username | empty | The sign-in account. Empty means no sign-in |
recipients | empty | Addresses that always receive, separated by commas |
sendToPerson | true | Also send to the person concerned. Set false to send only to recipients |
helo | localhost | The 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.
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 likesmtp host:587 (starttls), from …. - With
--send, it sends a real email to--toand torecipients.
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.
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"}}| Service | Kits | Default settings | Secret |
|---|---|---|---|
| Tara | TARA_NOTIFY_PLUGINS | TARA_NOTIFY_SETTINGS | TARA_NOTIFY_SECRET_KIT_NOTIFY_EMAIL |
| Ryoma | RYOMA_NOTIFY_PLUGINS | RYOMA_NOTIFY_SETTINGS | RYOMA_NOTIFY_SECRET_KIT_NOTIFY_EMAIL |
| Bandum | BANDUM_NOTIFY_PLUGINS | BANDUM_NOTIFY_SETTINGS | BANDUM_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.
- 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.
- Choose the Organization and the Plugin
kit-notify-email. - In Organization-specific settings, enter one
name=valueper line, for examplerecipients=pm@acme.example. Do not enter a password here: Tara rejects setting names that look like secrets. - Choose the events to receive, then save.
- In the row's actions menu, choose Send test.
You can do the same from the command line:
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-emailTroubleshooting
| Error text | Cause | Fix |
|---|---|---|
settings.host (SMTP server) is missing | No host | Add host |
settings.from must be an email address | from is empty or not an address | Use a full address such as alerts@example.com |
settings.security must be "starttls", "tls" or "none" | A wrong value | Use one of the three |
settings.username is set but the SMTP password is missing | username without the secret | Set <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_EMAIL and restart |
SMTP AUTH: 535 … | Wrong account or password. For Gmail, a normal password instead of an App password | Create 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 port | Use 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 it | Check the address and the network route |
STARTTLS with <host> failed (…) | The TLS handshake failed | Check the certificate of the server and the port |
the SMTP server did not respond | No answer within 20 seconds | Check the server and the route |
SMTP RCPT: 550 … | The server refuses a recipient or the sender | Fix 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
recipientsplus the people concerned (unlesssendToPersonisfalse). 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.