Send Custom Email on Event

With this built-in listener, your Bitbucket instance will send email notifications automatically after one or more events are triggered. You can configure which events this listener should be listening to and then provide a subject and email template, as well as the email format (plain text or HTML) and a list of recipients. There is also a conditions field, which can give more control over this functionality.

After selecting an event for the listener in the Events field, you can click on the '?' link to open the event class java doc. You can refer to this doc to find more variables that can be used when writing the email template. For example, if you select the ProjectPermissionModified event then that link opens its Java doc.

You can either create your own email templates or use one of the following samples that are included in the default installation of ScriptRunner:

Project Permission Modified

You can use the following template if you would like to get notified every time a permission is modified for a given project:

As a result of the modified project permissions, an email will be sent to the selected email addresses with content similar to the following one:

User admin has modified the permissions for project PROJECT_1.
Previous project permission: PROJECT_ADMIN.
New project permission: PROJECT_WRITE.
Affected group: stash-users.
Affected user: null.

ProjectPermissionModified is only triggered when a user's access to the project is changed, for example, from read to write. ProjectPermissionGranted or ProjectPermissionRevoked might also be needed in practice.

Repository Forked

This provides information about the repository that has just been created and the users that performed that fork. This is what the configuration of the listener would look like:

As a result of that configuration, an email will be sent to the selected email addresses with content similar to the following one:

User admin has forked the repository PROJECT_1/rep_1.
The name of the new repository is: PROJECT_1/myNewFork

Global Permissions Modified

If you would like to get notified every time a change is made in the Global permissions settings, you can use the following template:

An email similar to the following one will be sent after the permissions for a user have been modified:

User admin has modified the permissions for user user.
The highest global permission for this user is now: SYS_ADMIN

GlobalPermissionModified is only triggered when a user's access is changed, for example, from read to write. GlobalPermissionGranted or GlobalPermissionRevoked might also be needed in practice.

Additional Configuration in Emails

You may notice the syntax for getting content in the template is a bit clunky, as the template engine does not allow you to use the import keyword. Rather than doing this, you can pass in a config map to the bindings for both the subject and body templates. This is done in the Mail configuration section.

A simple example of a Mail configuration section that defines config variables for the RepositoryForkedEvent is:

groovy
import com.atlassian.sal.api.component.ComponentLocator
import com.atlassian.bitbucket.repository.RepositoryService

def repositoryService = ComponentLocator.getComponent(RepositoryService)
def originSize = repositoryService.getSize(event.repository.origin)

config["username"] = event.user.username 
config["projectKey"] = event.repository.origin.project.key 
config["originName"] = event.repository.origin.name 
config["originSize"] = originSize 
config["repoName"] = event.repository.name

The subject template:

groovy
User $config.username has forked a repository

The body template:

 
User $config.username has forked the repository $config.projectKey/$config.originName of size $config.originSize bytes.
The name of the new repository is: $config.projectKey/$config.repoName.

As a result of this configuration, an email will be sent to the selected email addresses with content similar to the following one:

User admin has forked the repository PROJECT_1/rep_1 of size 53248 bytes.
The name of the new repository is: PROJECT_1/myNewFork.


On this page