Skip to main content

Personal notifications

Besides the company's routes, Merge Pilot emails some events to the people they concern: the person a change approval is assigned to, the author of a blocked merge request, the company admins when a connection breaks. Each person chooses which of these emails they get, and every such email has a link that turns its kind of email off in one click.

Personal emails go through the company's mail server (SMTP configuration). Without one, none is sent.

Who gets what​

The recipients are worked out for each event:

Reason (as My profile shows it)Who that isEvents
When you are the assigneeThe person the change approval is assigned to now: in the built-in tracker their Merge Pilot account, in Jira the person the company's identity matching finds for the assigneeChange approval created, Change approval reassigned (the new assignee), Change approval due soon, Change approval overdue
When you may decide and nobody is assignedEveryone who may decide a change approval nobody could be assigned, as assignment would pick them from the policy's approversChange approval created
When you are the authorThe merge request's author: the one active person of the company who linked the author's VCS account on that connection in My profile. Nobody when no one, or more than one person, linked itMerge request blocked, Merge request refused, Not enough approvers, Change approval approved, Change approval rejected, and the scan findings: Secrets found in a merge request, Vulnerable dependency introduced by a merge request, Malicious package in a merge request, Denied license in a merge request, Dependency source problems in a merge request, CI configuration problems in a merge request, Vulnerable container images in a merge request, Infrastructure problems in a merge request
As a company adminThe company's active company adminsConnection problem, Connection recovered, Notification not delivered, License expiring, VCS access to review, Protection removed from a governed branch, Change approvals of a deactivated person, Service API token expiring, Connection token expiring, Identity provider unreachable, LDAP directory unreachable, Branch protection weakened, Direct change to a watched branch, Emergency declared, Emergency review overdue
About your accountThe person whose account it is aboutRole changed, API token expiring (their own personal token)

Every other event goes to the routes only. When the events are sent, how often and what they say is on Events; a personal email says the same as a route's, and is held back the same way (see What holds events back).

Only people who are active, belong to the event's company and have a valid email address get personal emails. A platform admin belongs to no company and gets none.

Your own actions​

Nobody gets a personal email about something they did themselves in Merge Pilot. A company admin who turns a connection off, removes a branch's protection or deactivates a person gets no email about it; the other company admins do. An admin who changes someone else's role does not get the Role changed email; the person whose role changed does. The routes get every event as usual.

One email per person​

A person who has several reasons for one event (for example the assignee who is also a company admin) gets one email. Its footer names the first of their reasons in the order of the table above: You get this because you are the assignee of this change approval, … you may decide this change approval and nobody is assigned to it, … you are the author of this merge request (pull request on GitHub), … you are a company admin, … it is about your account.

A route's address wins​

When an email route of the same event already sends to a person's address, that person gets the route's email only, not a personal one as well. The route's address is the company's choice, which the person's own unsubscribe could not stop. Addresses are compared without case.

Deactivated people​

A person who is deactivated, leaves the company, turns the event off, or no longer has the role the email was for (for example a company admin made a user before an admin email went out) after the email was queued gets nothing: the delivery is listed as Skipped in the delivery log. An email route that still sends to a deactivated person's address shows a warning on the route (see Routes).

Choosing in My profile​

My profile → Notifications (Emails Merge Pilot sends you personally, through your company's mail server: as a change approval's assignee or approver, as a change's author, as a company admin, or about your account. The company's notification routes are set apart by its admins.).

The card lists only the events that can reach you, in groups:

GroupEvents
Change approvalsThe events that go to an assignee
Your changesThe merge request events that go to the author
Scan findings in your changesThe scan findings that go to the author
Company administrationThe events that go to company admins (shown to company admins only)
Your accountRole changed, API token expiring

Each event has a switch and the reasons it can reach you (When you are the assignee, When you may decide and nobody is assigned, When you are the author, As a company admin, About your account). A switch is saved as soon as it is turned (Emails about “…” turned on / … turned off) and written to the audit log as notification_preferences_changed.

SettingWhat it doesDefaultWho can change itAPI field
One switch per eventWhether you get that event's personal emailsOn for every event, except Connection recovered (off unless you turn it on)The person themselvesevents of PUT /api/v1/auth/me/notification-preferences

When the company has no mail server, the card says Your company has no mail server set up, so no personal email is sent. Your choices are kept for when it has one. A platform admin sees Platform admins belong to no company, so they get no personal emails.

The switches change only personal emails. The company's routes are set by its admins on the Notifications tab.

Unsubscribe​

Every personal email ends with Unsubscribe from these emails and Notification settings (My profile → Notifications).

  • The link opens the Unsubscribe page, which says what it turns off (Stop emails about “…” to <user> in <company>.) and asks to confirm with Unsubscribe. Opening the link changes nothing by itself. Once confirmed: Done: you no longer get emails about “…”.; when that email was already off: You already get no emails about “…”.
  • One click. When Merge Pilot's address is HTTPS, the email also carries the standard one-click unsubscribe headers, so mail programs that offer an Unsubscribe button turn the email off directly, without opening a page.
  • What it turns off: that one event's personal emails, for that person, in that company: the same as turning its switch off in My profile. Other events, and the company's routes, are not changed. Turning the switch on again in My profile undoes it.
  • No sign-in is needed: the link itself is signed for that person, company and event. It works for 90 days after the email was sent, and only while the person is active in that company: once they are deactivated or leave it, the link is not valid and shows nothing about them. A changed, expired or otherwise invalid link shows This unsubscribe link is not valid or has expired. Change your notifications in My profile.
  • Each unsubscribe is written to the audit log as notification_unsubscribed, saying whether it came from a mail program's one-click button.

The delivery log never shows a personal email's unsubscribe link: whoever has it can use it.

When there is no mail server​

Without a mail server no personal email is sent, whatever the switches say, and nothing is queued. The audit log records it once a day as notification_personal_skipped (Personal notification emails are not sent: the company has no mail server). Routes of other channels still get their events.

API​

RequestWhoDoes
GET /api/v1/auth/me/notification-preferencesAny signed-in person or personal API token (not a service token)The events that can reach you: event, group, as (the reasons), enabled, default; and available (false for a platform admin), mail_server
PUT /api/v1/auth/me/notification-preferencesThe same{"events": {"mr_blocked": false}} turns the events given on or off; the others keep their choice. 400 for an event that is not sent to you, or for a platform admin
GET /api/v1/notifications/unsubscribe/details?t=<token>Anyone with the linkWhat the link turns off: event, company, username, enabled. 400 for an invalid or expired link, or a person no longer active in the company
POST /api/v1/notifications/unsubscribe?t=<token>Anyone with the linkTurns the event off (the page's button and the mail program's one-click button). 400 for an invalid or expired link, or a person no longer active in the company

See the API reference.