mailroom

README

Mailroom is a framework that simplifies the creation, routing, and delivery of user notifications based on events from external systems.

Mailroom is designed to be flexible and extensible, allowing you to easily add new event types and transports as your needs grow and evolve. Simply write code to transform incoming events into notifications, and Mailroom will take care of the rest, including:

• Acting as the primary notification relay for incoming webhooks from external systems
• Sending notifications to the appropriate users based on their preferences (e.g. PR reviews go to email, but build failures go to Slack)
• Formatting notifications for different transports (e.g. email, Slack, etc.)
• Matching usernames, emails, IDs, etc. across different systems
• Logging, error handling, retries, and more

See internal/example.go for an example of how to use mailroom.

Documentation

• Getting Started
• Core Concepts
• Integrations

Also see the GoDoc for documentation.

Stability

Mailroom is currently in alpha. It works well in production, but the API may change at any time. We will do our best to note breaking changes in the release notes.

Contributing

See CONTRIBUTING.md for contribution guidelines.

Use make to run all linters and tests locally.

Documentation

Overview

Mailroom is a notification relay framework

Index

• type Opt
  • func WithDefaultPreferences(prefs preference.Provider) Opt
  • func WithListenAddr(addr string) Opt
  • func WithParser(key string, parser event.Parser) Opt
  • func WithParserAndGenerator(key string, parser event.Parser, generator event.Processor) Opt
  • func WithProcessors(processors ...event.Processor) Opt
  • func WithRouter(router *mux.Router) Opt
  • func WithTransports(transports ...notifier.Transport) Opt
  • func WithUserStore(us user.Store) Opt
• type Server
  • func New(opts ...Opt) *Server
  • func (s *Server) Run(ctx context.Context) error

Types

type Opt

type Opt func(s *Server)

func WithDefaultPreferences

func WithDefaultPreferences(prefs preference.Provider) Opt

WithDefaultPreferences sets the default preferences for the server

func WithListenAddr

func WithListenAddr(addr string) Opt

WithListenAddr sets the IP and port the server listens on, in the form "host:port"

func WithParser

func WithParser(key string, parser event.Parser) Opt

WithParser adds an event.Parser to the server with the given key. The key is used as the API endpoint for the server.

func WithParserAndGenerator

func WithParserAndGenerator(key string, parser event.Parser, generator event.Processor) Opt

WithParserAndGenerator is a convenience function that adds an event.Parser and its corresponding processor (which generates notifications) in a single call.

func WithProcessors

func WithProcessors(processors ...event.Processor) Opt

WithProcessors adds event.Processor instances to the server in the order given.

func WithRouter

func WithRouter(router *mux.Router) Opt

WithRouter sets the mux.Router used for the server

func WithTransports

func WithTransports(transports ...notifier.Transport) Opt

WithTransports adds notifier.Transport instances to the server

func WithUserStore

func WithUserStore(us user.Store) Opt

WithUserStore sets the user.Store for the server

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is the heart of the mailroom application It listens for incoming webhooks, parses them, generates notifications, and dispatches them to users.

func New

func New(opts ...Opt) *Server

New returns a new server

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run starts the server in a Goroutine and blocks until the server is shut down. If the given context is canceled, the server will attempt to shut down gracefully.