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 -> Notification page 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:

  1. Fill in all required fields.

    • Use the suggested canonical server URL unless there is a known reason to change it.

    • Set a valid From email address.

    • Set a repository nickname.

  2. Set Email Send Method to Pipe to a command.

  3. Set Administrator email address to a valid administrator address.

  4. 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 sendmail -ti. This is the common quick setup.

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 alerts

  • vb test-alert

  • vb test-add-alerts

  • vb 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.