This section covers the core concepts of the Mailroom framework. Familiarity with these concepts is essential for extending and customizing Mailroom to suit your needs.
An Event is some action that occurs in an external system that we want to send a Notification for. Events are the primary input to Mailroom and are used to generate notifications for users.
Typically, these will come in the form of a webhook sent by an external system which is then processed by a Handler.
A Handler processes an incoming Event (HTTP webhook) from a Source and returns any number of Notifications to send. It must implement the handler.Handler interface.
The most important method is Process(), which takes an incoming HTTP request and returns a list of Notifications to send.
Handlers may return:
- No notifications (perhaps the event is not of interest)
- One notification
- Multiple notifications
- An error
For example, a GitHub handler might listen for pull request creation events and send a notification to the author, reviewers, and/or assignees of the PR.
A Handler can optionally be composed of separate Payload Parser and Notification Generator objects:
A Payload Parser implements the handler.PayloadParser interface and is responsible for:
- Receiving a serialized Event via an incoming HTTP request
- Validating the request (e.g. verifying the signature or shared secret)
- Parsing the raw request body into a useful Event object if the event is of interest to us
The resulting Event object is then passed to the Notification Generator.
A Notification Generator implements the handler.NotificationGenerator interface and takes the parsed Event and generates one or more Notifications from it.
A Notification is a common.Notification object that should be sent to a User via some Transport. It consists of some metadata about the origins of the notification, the intended recipient, and the message to send them.
Notifications are generated by Handlers and are passed to the Notifier for delivery.
A notification can only be sent to one user. If a notification needs to be sent to multiple users, it should be duplicated for each user.
The Notifier is responsible for taking the generated Notifications and dispatching them to the appropriate Transports for delivery based on the User's Preferences.
A Transport is a way to send a Notification to a User. It could be email, Slack, Discord, or something else.
Each Transport must implement the notifier.Transport interface and can choose how to deliver the notification to the user.
A User is a person who wants to receive Notifications from Mailroom. They may have Preferences on how they'd like to receive them.
Each user has a set of Identifiers that uniquely identify them across different systems.
An Identifier is a unique string that identifies an initiator or potential recipient (User) of some event. It could be an email address, a Slack user ID, or something else.
Each identifier is composed of three parts:
- Namespace (optional): The namespace of the identifier (e.g.
slack.com,github.com) - Kind: The kind of identifier (e.g.
email,username,id) - Value: The actual value of the identifier (e.g.
rufus@seatgeek.com,rufus,U123456)
For example, the slack.com/email:rufus@seatgeek.com identifier means that Slack knows this user by the email address rufus@seatgeek.com.
Identifiers are an important concept in Mailroom - they allow us to match users across different systems and ensure that notifications are sent to the correct person. This is because a user may be known by different identifiers in different systems; for example:
- Slack knows users by email address and Slack ID (e.g.
U123456) - GitHub knows users by username and email address
- etc.
Imagine we receive an event from GitHub that should notify a user in Slack. We may need to cross-reference their email addresses across both systems to determine their Slack ID given their GitHub username. Mailroom can automatically facilitate this matching process for you.
An Identifier Set is a collection of all known Identifiers that are associated with a single User.
The identifier set can only have one identifier of each namespace+kind. This is why the optional namespace is included in the identifier - it allows us to differentiate between two identifiers of the same kind (like two different email addresses) that are associated with the same user.
Mailroom supports the ability for each User to specify which Notifications they want to receive, and which Transports they prefer to receive them on. This is done via Preferences.
These can be set via the Mailroom API and are stored in the User Store.
The User Store is a database that stores user information, including their Identifiers and Preferences. It is used by Mailroom to look up user information when processing incoming events and generating notifications.