Core Concepts¶

Transport¶

Transport is the underlying platform that performs notifications, either out of the box from Home Assistant, or another custom component
Transport Adaptors are what make the difference between regular Notify Groups and Supernotify. While a Notify Group seems to allow easy multi-channel notifications, in practice each notify transport has different data (and data inside data!) structures, addressing etc so in the end notifications have to be simplified to the lowest common set of attributes, like just message!
Supernotify comes out the box with adaptors for common transports, like e-mail, mobile push, SMS, and Alexa, and a Generic transport adaptor that can be used to wrap any other Home Assistant action
The transport adaptor allows a single notification to be sent to many platforms, even when they all have different and mutually incompatible interfaces. They adapt notifications to the transport, pruning out attributes they can't accept, reshaping data structures, selecting just the appropriate targets, and allowing additional fine-tuning where its possible.
Transport Adaptors can optionally be defined in the Supernotify config with defaults
See Transports for more detail

A Delivery defines each notification channel you want to use
While Supernotify comes with many transports, only the ones you define with a Delivery will get used to send notifications, with the exception of Notify Entity transport which is always on unless switched off.
Deliveries allow lots of fine tuning and defaults to be made, and you can also have multiple deliveries for a single transport, for example a plain_email and html_email deliveries.
See Deliveries and Recipes for more detail

An easy way to package up common chunks of config, optionally combined with conditional logic
Scenarios can be manually selected, in an apply_scenarios value of notification data block, or automatically selected using a standard Home Assistant condition block.
They make it easy to apply overrides in one place to many different deliveries or notifications, and are the key to making notification calls in your automations radically simpler
See Scenarios and Recipes for more detail

The target of a notification.
This could be a direct target, like an entity_id, device_id, e-mail address, phone number, or some custom ID for a specialist transport like Telegram or API calls.
It also has some support, more to come, for indirect targets. The primary one is person_id, although some other Home Assistant ones will be supported in future, like label_id,floor_id and area_id.
There's also the in-between type, group, which is sort of both indirect and direct. Supernotify will exploded these for the Chime integration, but otherwise ignore them.

Define a person, with optional e-mail address, phone number, mobile devices or custom targets.
This lets you target notifications to people in notifications, and each transport will pick the type of target it wants, for example the SMS one picking phone number and the SMTP one an e-mail address
See People and Recipes for more detail

A notification customized for a specific delivery
- List of targets filtered, for example, only e-mail addresses for SMTP integration
- Indirect targets, like person.xxx are materialized into e-mail addresses, phone numbers etc
- The data section of the notification may also have been customized, by the delivery definition, or application of a scenario.
Envelope isn't present in the configuration - aside from the code, its only visible when viewing an archived notification, where a list of delivered and undelivered envelopes is kept.

An urgency level for notifications
There is no standard way to prioritize notifications, within or outside Home Assistant
Supernotify has its own 5 level scheme, which follows the most common practices, from minimum to critical
Priority can be used for things like scenario and delivery rules, and passed onto notify integrations that support it

Info

For the technically minded, there's a Class Diagram of the core classes matching these concepts.

All a notification needs is a message, everything else can be defaulted, including all the targets
If you define something in an action call, it takes precedence over the defaults - This can be tuned by things like target_usage - The people registry is only used to generate targets if no targets given
Action > Scenario > Delivery > Transport for configuration and defaults
As unfussy as possible about how it is configured and called - Targets can be structured into sub-categories, or a bit list of entity ids, device ids, emails and phone numbers - Action data options like delivery can be a single value, list or dictionary mapping