Warning
The product is in closed beta and not open to the public.
Email Alerts¶
Email alerts let a VisionByte server send email messages when repository activity occurs. Alerts can be sent immediately, or collected into a daily digest.
Alerts can be generated for these event types:
New check-ins.
Ticket changes.
Wiki page changes.
New or edited forum posts.
New permissions granted to users. This alert type is for administrators only.
Announcements.
Email alerts require a VisionByte server. They do not work when VisionByte is used only from the command line.
VisionByte uses the terms email alerts and notifications for the
same feature. This page uses email alerts unless it refers to a user
interface label.
Prerequisites¶
To configure email alerts, use a VisionByte account with the Admin
capability.
Open these two interfaces:
The
Admin->Notificationpage on the VisionByte server.A command-line shell in a checkout of the repository.
If the shell is not in a checkout directory, add -R /path/to/repo to
repository-specific vb commands.
Quick Setup¶
Use this setup when the server already has a working mail transfer agent, such as OpenSMTPD, Postfix, Exim, or Sendmail, and VisionByte is not isolated from it by a chroot or similar environment.
On the Admin -> Notification page:
Fill in all required fields.
Use the suggested canonical server URL unless there is a known reason to change it.
Set a valid
Fromemail address.Set a repository nickname.
Set
Email Send MethodtoPipe to a command.Set
Administrator email addressto a valid administrator address.Save the changes.
Then verify the send command:
$ vb set email-send-command
If the command is empty, set it explicitly:
$ vb set email-send-command "sendmail -ti"
Many mail systems, including Postfix and Exim, provide a sendmail
compatible command. VisionByte can use that compatibility command without
knowing which mail system is installed.
After setup, the status area on the notification page should show that
outgoing email is piped to sendmail -ti. It should also show the
number of pending alerts and subscribers.
Subscribing¶
Users subscribe through the /subscribe page.
A subscriber may be either:
A VisionByte user account that also receives email alerts.
An email-only subscriber without a VisionByte login.
If a logged-in user enters the same username and email address used in that user’s VisionByte account, VisionByte connects the subscription to that account. Otherwise, VisionByte creates an email-only subscriber record.
New email-only subscribers must verify their email address before VisionByte sends alerts to them. VisionByte sends one verification email. If that email is lost or not completed, an administrator must reset or verify the subscription.
A user must have the Email Alerts capability to use the subscription
pages. Admin and Setup users always have this capability.
Subscription Management¶
Subscribers manage their alert settings through the /alerts page.
To unsubscribe, use the /alerts page, select Unsubscribe, confirm
the action, and submit the form again. The confirmation step prevents
accidental unsubscription.
Email-only subscribers receive management links in alert email footers. Those links include a subscriber security code. Anyone with that code can modify that subscription, so alert emails should be treated as sensitive.
Testing¶
The simplest test is to use the Send Announcement link on the
notification setup page. Send a test message to your own address and
verify that the message is delivered.
You can also send a test message from the command line:
$ vb alerts test-message you@example.com --body README.md --subject Test
This sends an email to you@example.com with the subject Test and
the contents of README.md as the message body.
Troubleshooting¶
Use these commands from a checkout of the repository.
Show alert configuration and queue status:
$ vb alerts status
Run the backoffice process, which sends queued alert emails:
$ vb backoffice
Send pending alerts:
$ vb alerts send
Show pending alerts:
$ vb alert pending
Create a test alert for a forum post, then send pending alerts:
$ vb test-add-alerts f5900
$ vb alert send
In the test alert argument, f means forum alert. The number is the ID
of a forum post.
If pending alerts exist but no email arrives, check the mail server logs
and the recipient spam folder. If pending alerts remain queued, run
vb backoffice or vb alerts send and check the status
again.
Email Sending Methods¶
VisionByte supports several email delivery methods.
Method |
Meaning |
|---|---|
Pipe to a command |
VisionByte writes the email message to a command such as
|
Store in a database |
VisionByte writes outgoing messages to an SQLite database. A separate process reads that database and sends the messages. |
Store in a directory |
VisionByte writes outgoing messages as files in a directory. Another process can read and send them. |
SMTP relay |
VisionByte sends messages to an SMTP relay. This is appropriate only when the relay accepts the connection safely. |
Direct SMTP send |
VisionByte sends directly to recipients by SMTP. |
Pipe to a Command¶
When using Pipe to a command, VisionByte writes the email message in RFC
822 format to the command’s standard input.
The usual command is:
sendmail -ti
The -t option tells the command to read recipients from the email
headers. The -i option prevents a line containing only a period from
ending the message early on mail systems that use that convention.
The msmtp SMTP client can also be used with the -t option.
Users and Subscribers¶
VisionByte stores users and subscribers separately.
A user has a VisionByte login name and password. A subscriber receives email alerts. A person may be both a user and a subscriber, but this is not required.
Administrators can view and manage subscribers from the List
Subscribers button on the notification setup page. From that page, an
administrator can verify addresses, change subscription settings, mark an
address as do-not-call, or connect a subscriber to a VisionByte user account.
Useful Pages and Commands¶
User and subscriber pages:
/subscribe/alerts/unsubscribe/renew/contact_admin
Administrator pages:
/setup_notification/subscribers
Commands:
vb alertsvb test-alertvb test-add-alertsvb backoffice
Implementation Notes¶
Email alert data is stored in repository database tables that are created when alerts are configured and used.
The subscriber table stores subscriber email addresses, preferences, verification state, and subscriber security codes. The pending-alert queue stores repository events that may need alert emails.
When alerts are enabled, VisionByte records new timeline events into the pending-alert queue. The backoffice process then sends the matching messages. Calling the send process more than once does not duplicate alerts that were already moved through the queue.
Digest email delivery is controlled by the last digest time. VisionByte sends a new digest only when the configured digest interval has elapsed.