codician/diffinerypublic

---

#title: Notifications description: In-app notifications and email from Diffinery: every email group and template, settings, watching, thread subscriptions, unsubscribe links, headers and the API.

Diffinery tells you about activity in two places: the notifications list in the web UI, and email. Both follow GitHub's rules: you hear about issues and pull requests you take part in, everything in repositories you watch, and workflow runs you started. This page explains what you get, how to change it, and every email Diffinery can send.

#The notifications list and notification settings

Two pages share the name, and they do different things:

The list only shows what your settings let through. To get fewer (or more) entries in the list, change the On Diffinery column in the settings; to change your email, change the Email column.

#The notifications list

The bell in the header opens Notifications (/notifications). It has two views, Unread and All, and shows your 100 most recent notifications. Each entry has an icon for its kind (a pull request, an issue, a comment, a failed run in red, an organization or a repository), a title such as diffy commented on acme/website#42: Cache build artifacts, its kind (for example issue comment, pull request review or run failed) and when it happened.

• Click an entry to open what it is about; that marks it read.
• Click the check mark (Mark as read) next to an unread entry to mark only that one read.
• Click Mark all as read to clear the list.
• Click the gear button (Notification settings) to open Settings → Notifications.

Your dashboard also shows up to 8 unread notifications under Unread notifications.

You get an in-app notification for:

• issue and pull request activity you take part in, when Participating → On Diffinery is on,
• activity in repositories you watch with All activity, when Watching → On Diffinery is on,
• failed workflow runs you started, when Actions → On Diffinery is on,
• someone adding you to an organization with Add people (kind org membership, for example "<admin> added you to acme as a member"),
• someone giving you access to a repository with Add people (kind repo access, for example "<admin> gave you write access to acme/website").

The last two are always sent, whatever your settings; the matching emails belong to the Organizations and Repositories groups.

Your own actions never create a notification for you. Other repository and organization events (role changes, removals, repositories created or deleted), and security and account events, are sent by email only.

#Email groups

Every email belongs to one group. Security and account emails always send; you can turn the others off.

#Notification settings

Open Settings → Notifications (/settings/notifications). The top of the page shows the address emails go to (your account's email address) and the address they come from (notifications@diffinery.com).

The Notify me about table has a row per group with an On Diffinery checkbox (the notifications list) and an Email checkbox:

Below the table:

• Email me about my own comments and changes (off by default). When on, you also get emails about comments, reviews and changes you made yourself, like GitHub's "Include your own updates".
• Watch repositories I create (All activity) (on by default). New repositories you create, in the web UI or through the API, are watched with All activity.

Click Save notification settings. You see "Notification settings saved."

The same page lists Watched repositories (every repository you watch or ignore, with a menu to change the level) and Recent emails to you (the last 20, with their status), and has a Send me a test email button.

#Who gets notified about issues and pull requests

For each event on an issue or pull request, Diffinery works out who is taking part:

When several apply, the email gives the first one in this order. Mentions use @username outside code blocks and inline code.

What sends:

Rules that apply to every event:

• Your own actions don't notify you, unless you turn on Email me about my own comments and changes (email only; such emails carry the reason your_activity).
• A repository set to Ignore sends you nothing about its issues and pull requests.
• A muted thread (you clicked Unsubscribe) sends you nothing, except when that event @mentions you, assigns you or asks for your review.
• You must still be able to read the repository. People who lost access stop hearing about it.
• Agents don't receive email.

#Watch a repository

The Watch menu at the top of every repository sets how much you hear about it:

Choosing a level saves it right away ("Watching acme/website: All activity."). You can also change levels from the Watched repositories list in Settings → Notifications.

With the API (GitHub's repository subscription endpoints):

# Watch all activity
curl -X PUT https://diffinery.com/api/v3/repos/acme/website/subscription \
  -H "Authorization: Bearer dfy_..." -H "Content-Type: application/json" \
  -d '{"subscribed": true}'

# Ignore the repository
curl -X PUT https://diffinery.com/api/v3/repos/acme/website/subscription \
  -H "Authorization: Bearer dfy_..." -H "Content-Type: application/json" \
  -d '{"ignored": true}'

# Back to participating only
curl -X DELETE https://diffinery.com/api/v3/repos/acme/website/subscription \
  -H "Authorization: Bearer dfy_..."

GET /api/v3/repos/{owner}/{repo}/subscription returns {"subscribed": true|false, "ignored": true|false, ...}, or 404 not subscribed when you are on the default participating level (as GitHub does). PUT with {"subscribed": false} also returns you to participating. Changing the level needs a write or admin token.

#Subscribe to or mute an issue or pull request

The sidebar of every issue and pull request has a Notifications section with one button:

• Subscribe follows the thread even if you aren't taking part: "Subscribed. You'll be notified about all activity."
• Unsubscribe mutes it: "Unsubscribed. You'll still be notified if you're @mentioned, assigned or asked to review."

The text under the button says why you are or aren't receiving notifications, for example "You're receiving notifications because you commented." or "You muted this pull request."

#Workflow run notifications

When a workflow run finishes:

Failed and timed-out runs send an email and an in-app notification. Successful runs send an email only to people who turned off Only failed runs. Cancelled runs send nothing. The email lists every job with its result and the first failure message, and links to the run.

#Unsubscribe links

Every email in a group you can turn off has unsubscribe links in its footer, and List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click headers (RFC 8058), so mail apps show their own Unsubscribe button.

The mail app's one-click button uses the first link: muting the thread for issue and pull request emails, turning off the group for the rest.

The links are signed, so they work without signing in and can't be altered to change someone else's settings. Opening one shows a page naming the change and the account (for example "Mute acme/website#42") with a button to confirm; after confirming you can click Undo. Security and account emails have no unsubscribe links.

#Email headers

Every email has an HTML and a plain-text version and these headers, which you can use in mail filters:

#X-Diffinery-Reason values

#Every email Diffinery sends

The Kind column is the X-Diffinery-Kind header. Site administrators can preview every one of these under Settings → Email (see Site administration).

Issue and pull request emails (thread) come in these variants:

#Send a test email

Click Send me a test email on Settings → Notifications. Diffinery sends it right away (not through the queue) and shows "Test email sent to <address>." or the reason it wasn't sent, for example "The test email was skipped: ...".

With the API (needs a write or admin token that isn't limited to repositories):

curl -X POST https://diffinery.com/api/v3/diffinery/emails/test -H "Authorization: Bearer dfy_..."

{ "status": "sent", "messageId": "..." }

status is sent, skipped or failed, with a detail when it wasn't sent.

#Notifications API

The settings object, with its defaults:

{
  "participating": { "web": true, "email": true },
  "watching": { "web": true, "email": true },
  "actions": { "web": true, "email": true, "failuresOnly": true },
  "repos": { "email": true },
  "orgs": { "email": true },
  "ownActivity": false,
  "autoWatch": true
}

For example, to stop watching emails and get every workflow run result:

curl -X PUT https://diffinery.com/api/v3/diffinery/notification-settings \
  -H "Authorization: Bearer dfy_..." -H "Content-Type: application/json" \
  -d '{"watching": {"email": false}, "actions": {"failuresOnly": false}}'

The response is the full settings object. An unknown key returns 422 unknown setting <key>. Only people have notification settings; agent tokens get 403 only people have notification settings.

#Delivery

Emails are queued and sent through Cloudflare Email Sending from notifications@diffinery.com. A failed send is retried with increasing delays. Every email Diffinery tries to send is logged for 90 days with its status, which you can see under Recent emails to you or with GET /api/v3/diffinery/emails. A skipped email has a reason:

#How notifications differ from GitHub

• The participating, watching and ignore rules, @mention handling, thread subscriptions, X-Diffinery-Reason (for X-GitHub-Reason) and the /repos/{owner}/{repo}/subscription API follow GitHub.
• Diffinery has no custom watch level (such as releases or discussions only).
• Settings are per group, for the notifications list and email separately. There are no per-organization email routes; every email goes to your account's address.
• Security and account emails can't be turned off.
• The notifications list shows your 100 most recent notifications and has no per-thread done or saved states.
• Being added to an organization or a repository with Add people always creates an in-app notification, with no setting to turn it off.