Connect#

Sonarr supports configuring connections to external applications and services.

These are not only for Sonarr to communicate with the outside world, they can also be useful for monitoring since the user can be alerted by a variety of possible service when some kind of event (or problem) occurs in Sonarr.

Configuring connections#

Connections are configured using the following syntax.

sonarr:
  settings:
    connect:
      delete_unmanaged: false # Optional
      definitions:
        Email: # Name of connection in Sonarr.
          type: "email" # Required
          notification_triggers: # When to send notifications.
            on_grab: true
            on_import: true
            on_upgrade: true
            on_rename: false # Not supported by email notifications.
            on_series_delete: true
            on_episode_file_delete: true
            on_episode_file_delete_for_upgrade: true
            on_health_issue: true
            include_health_warnings: false # Do not send on just warnings.
            on_application_update: true
          tags: # Tags can also be assigned to connections.
            - "example"
          # Connection-specific parameters.
          server: "smtp.example.com"
          port: 465
          use_encryption: true
          username: "sonarr"
          password: "fake-password"
          from_address: "sonarr@example.com"
          recipient_addresses:
            - "admin@example.com"
        # Add additional connections here.

A type attribute must be defined so Buildarr knows what type of connection to make. Each connection has a unique value for type documented below.

The triggers enabled on a connection are defined under notification_triggers. Tags can be assigned to connections, to only allow notifications relating to media under those tags.

The delete_unmanaged flag on the outer connect block can be set to remove connections not defined in Buildarr. Take care when using this option, as it can remove connections automatically managed by other applications.

The following notification triggers can be enabled. Some connection types only allow a subset of these to be enabled, check the documentation the specific connection type for more information.

on_grab: bool = False class-attribute instance-attribute #

Be notified when episodes are available for download and has been sent to a download client.

on_import: bool = False class-attribute instance-attribute #

Be notified when episodes are successfully imported. (Formerly known as On Download)

on_upgrade: bool = False class-attribute instance-attribute #

Be notified when episodes are upgraded to a better quality.

on_rename: bool = False class-attribute instance-attribute #

Be notified when episodes are renamed.

on_series_delete: bool = False class-attribute instance-attribute #

Be notified when series are deleted.

on_episode_file_delete: bool = False class-attribute instance-attribute #

Be notified when episodes files are deleted.

on_episode_file_delete_for_upgrade: bool = False class-attribute instance-attribute #

Be notified when episode files are deleted for upgrades.

on_health_issue: bool = False class-attribute instance-attribute #

Be notified on health check failures.

include_health_warnings: bool = False class-attribute instance-attribute #

Be notified on health warnings in addition to errors.

Requires on_health_issue to be enabled to have any effect.

on_application_update: bool = False class-attribute instance-attribute #

Be notified when Sonarr gets updated to a new version.

Boxcar#

Receive media update and health alert push notifications via Boxcar.

Supported notification triggers: All except on_rename

type: Literal['boxcar'] = 'boxcar' class-attribute instance-attribute #

Type value associated with this kind of connection.

access_token: Password instance-attribute #

Access token for authenticating with Boxcar.

Custom Script#

Execute a local script on the Sonarr instance when events occur.

Supported notification triggers: All

type: Literal['customscript'] = 'customscript' class-attribute instance-attribute #

Type value associated with this kind of connection.

path: NonEmptyStr instance-attribute #

Path of the script to execute.

Discord#

Send media update and health alert messages to a Discord server.

Supported notification triggers: All

type: Literal['discord'] = 'discord' class-attribute instance-attribute #

Type value associated with this kind of connection.

webhook_url: AnyHttpUrl instance-attribute #

Discord server webhook URL.

username: Optional[str] = None class-attribute instance-attribute #

The username to post as.

If unset, blank or set to None, use the default username set to the webhook URL.

avatar: Optional[str] = None class-attribute instance-attribute #

Change the avatar that is used for messages from this connection.

If unset, blank or set to None, use the default avatar for the user.

host: Optional[str] = None class-attribute instance-attribute #

Override the host name that shows for this notification.

If unset, blank or set to None, use the machine name.

on_grab_fields: Set[OnGrabField] = {OnGrabField.overview, OnGrabField.rating, OnGrabField.genres, OnGrabField.quality, OnGrabField.size, OnGrabField.links, OnGrabField.release, OnGrabField.poster, OnGrabField.fanart} class-attribute instance-attribute #

Set the fields that are passed in for this 'on grab' notification. By default, all fields are passed in.

Values:

  • overview
  • rating
  • genres
  • quality
  • group
  • size
  • links
  • release
  • poster
  • fanart

Example:

...
  connect:
    definitions:
      Discord:
        type: "discord"
        webhook_url: "https://..."
        on_grab_fields:
          - "overview"
          - "quality"
          - "release"
on_import_fields: Set[OnImportField] = {OnImportField.overview, OnImportField.rating, OnImportField.genres, OnImportField.quality, OnImportField.codecs, OnImportField.group, OnImportField.size, OnImportField.languages, OnImportField.subtitles, OnImportField.links, OnImportField.release, OnImportField.poster, OnImportField.fanart} class-attribute instance-attribute #

Set the fields that are passed in for this 'on import' notification. By default, all fields are passed in.

Values:

  • overview
  • rating
  • genres
  • quality
  • codecs
  • group
  • size
  • languages
  • subtitles
  • links
  • release
  • poster
  • fanart

Example:

...
  connect:
    definitions:
      Discord:
        type: "discord"
        webhook_url: "https://..."
        on_import_fields:
          - "overview"
          - "quality"
          - "release"

Email#

Send media update and health alert messages to an email address.

Supported notification triggers: All except on_rename

type: Literal['email'] = 'email' class-attribute instance-attribute #

Type value associated with this kind of connection.

server: NonEmptyStr instance-attribute #

Hostname or IP address of the SMTP server to send outbound mail to.

port: Port = 587 class-attribute instance-attribute #

The port number on the SMTP server to use to submit mail.

The default is to use STARTTLS on the standard SMTP submission port.

use_encryption: bool = True class-attribute instance-attribute #

Whether or not to use encryption when sending mail to the SMTP server.

If the port number is set to 465, SMTPS (implicit TLS) will be used. Any other port number will result in STARTTLS being used.

The default is to enable encryption.

username: NonEmptyStr instance-attribute #

SMTP username of the account to send the mail from.

password: Password instance-attribute #

SMTP password of the account to send the mail from.

from_address: EmailStr instance-attribute #

Email address to send the mail as.

Changed in version 0.5.3: Disallow RFC-5322 formatted mailbox addresses (e.g. Sonarr Notifications <sonarr@example.com>), as they are not supported by Sonarr V3 (the currently supported version).

recipient_addresses: Annotated[List[EmailStr], Field(min_items=1, unique_items=True)] instance-attribute #

List of email addresses to directly address the mail to.

At least one address must be provided.

Changed in version 0.5.3: Disallow RFC-5322 formatted mailbox addresses (e.g. Sonarr Notifications <sonarr@example.com>), as they are not supported by Sonarr V3 (the currently supported version).

cc_addresses: Annotated[List[EmailStr], Field(unique_items=True)] = [] class-attribute instance-attribute #

Optional list of email addresses to copy (CC) the mail to.

Changed in version 0.5.3: Disallow RFC-5322 formatted mailbox addresses (e.g. Sonarr Notifications <sonarr@example.com>), as they are not supported by Sonarr V3 (the currently supported version).

bcc_addresses: Annotated[List[EmailStr], Field(unique_items=True)] = [] class-attribute instance-attribute #

Optional list of email addresses to blind copy (BCC) the mail to.

Changed in version 0.5.3: Disallow RFC-5322 formatted mailbox addresses (e.g. Sonarr Notifications <sonarr@example.com>), as they are not supported by Sonarr V3 (the currently supported version).

Emby#

Send media update and health alert notifications to an Emby server.

Supported notification triggers: All

type: Literal['emby'] = 'emby' class-attribute instance-attribute #

Type value associated with this kind of connection.

host: NonEmptyStr instance-attribute #

Emby server hostname or IP address.

port: Port = 8096 class-attribute instance-attribute #

Emby server port.

use_ssl: bool = False class-attribute instance-attribute #

Use HTTPS to connect to Emby, instead of HTTP.

api_key: Password instance-attribute #

API key to authenticate with Emby.

send_notifications: bool = False class-attribute instance-attribute #

Have MediaBrowser send notifications to configured providers.

update_library: bool = False class-attribute instance-attribute #

Update the Emby library on import, rename, or delete.

Gotify#

Send media update and health alert push notifications via a Gotify server.

Supported notification triggers: All except on_rename

type: Literal['gotify'] = 'gotify' class-attribute instance-attribute #

Type value associated with this kind of connection.

server: AnyHttpUrl instance-attribute #

Gotify server URL. (e.g. http://gotify.example.com:1234)

app_token: Password instance-attribute #

App token to use to authenticate with Gotify.

priority: GotifyPriority = GotifyPriority.normal class-attribute instance-attribute #

Gotify notification priority.

Values:

  • min
  • low
  • normal
  • high

Join#

Send media update and health alert push notifications via Join.

Supported notification triggers: All except on_rename

type: Literal['join'] = 'join' class-attribute instance-attribute #

Type value associated with this kind of connection.

api_key: Password instance-attribute #

API key to use to authenticate with Join.

device_names: Set[NonEmptyStr] = set() class-attribute instance-attribute #

List of full or partial device names you'd like to send notifications to.

If unset or empty, all devices will receive notifications.

priority: JoinPriority = JoinPriority.normal class-attribute instance-attribute #

Join push notification priority.

Values:

  • silent
  • quiet
  • normal
  • high
  • emergency

Kodi (XBMC)#

Send media update and health alert notifications to a Kodi (XBMC) instance.

Supported notification triggers: All

type: Literal['kodi', 'xbmc'] = 'kodi' class-attribute instance-attribute #

Type values associated with this kind of connection. (Use either one)

host: NonEmptyStr instance-attribute #

Kodi hostname or IP address.

port: Port = 8080 class-attribute instance-attribute #

Kodi API port.

use_ssl: bool = False class-attribute instance-attribute #

Connect to Kodi over HTTPS instead of HTTP.

username: NonEmptyStr instance-attribute #

Username to use to login to Kodi.

password: Password instance-attribute #

Password to use to login to Kodi.

gui_notification: bool = False class-attribute instance-attribute #

Enable showing notifications from Sonarr in the Kodi GUI.

display_time: int = Field(5, ge=0) class-attribute instance-attribute #

How long the notification will be displayed for (in seconds).

update_library: bool = False class-attribute instance-attribute #

Update the Kodi library on import/rename.

clean_library: bool = False class-attribute instance-attribute #

Clean the Kodi library after update.

always_update: bool = False class-attribute instance-attribute #

Update the Kodi library even when a video is playing.

Mailgun#

Send media update and health alert emails via the Mailgun delivery service.

Supported notification triggers: All except on_rename

type: Literal['mailgun'] = 'mailgun' class-attribute instance-attribute #

Type value associated with this kind of connection.

api_key: Password instance-attribute #

API key to use to authenticate with Mailgun.

use_eu_endpoint: bool = False class-attribute instance-attribute #

Send mail via the EU endpoint instead of the US one.

from_address: EmailStr instance-attribute #

Email address to send the mail as.

Changed in version 0.5.3: Disallow RFC-5322 formatted mailbox addresses (e.g. Sonarr Notifications <sonarr@example.com>), as they are not supported by Sonarr V3 (the currently supported version).

sender_domain: NonEmptyStr instance-attribute #

The domain from which the mail will be sent.

recipient_addresses: Annotated[List[EmailStr], Field(min_items=1, unique_items=True)] instance-attribute #

The recipient email addresses of the notification mail.

At least one recipient address is required.

Changed in version 0.5.3: Disallow RFC-5322 formatted mailbox addresses (e.g. Sonarr Notifications <sonarr@example.com>), as they are not supported by Sonarr V3 (the currently supported version).

Plex Home Theater#

Send media update notifications to a Plex Home Theater instance.

Supported notification triggers: on_grab, on_import, on_upgrade only

type: Literal['plex-home-theater'] = 'plex-home-theater' class-attribute instance-attribute #

Type value associated with this kind of connection.

host: NonEmptyStr instance-attribute #

Plex Home Theater hostname or IP address.

port: Port = 3005 class-attribute instance-attribute #

Plex Home Theater API port.

use_ssl: bool = False class-attribute instance-attribute #

Connect to Plex Home Theater over HTTPS instead of HTTP.

username: NonEmptyStr instance-attribute #

Username to use to login to Plex Home Theater.

password: Password instance-attribute #

Password to use to login to Plex Home Theater.

gui_notification: bool = False class-attribute instance-attribute #

Enable showing notifications from Sonarr in the Plex Home Theater GUI.

display_time: int = Field(5, ge=0) class-attribute instance-attribute #

How long the notification will be displayed for (in seconds).

update_library: bool = False class-attribute instance-attribute #

Update the Plex Home Theater library on import/rename.

clean_library: bool = False class-attribute instance-attribute #

Clean the Plex Home Theater library after update.

always_update: bool = False class-attribute instance-attribute #

Update the Plex Home THeater library even when a video is playing.

Plex Media Center#

Send media update notifications to a Plex Media Center instance.

Supported notification triggers: on_grab, on_import, on_upgrade only

type: Literal['plex-media-center'] = 'plex-media-center' class-attribute instance-attribute #

Type value associated with this kind of connection.

host: NonEmptyStr instance-attribute #

Plex Media Center hostname or IP address.

port: Port = 3000 class-attribute instance-attribute #

Plex Media Center API port.

username: NonEmptyStr instance-attribute #

Username to use to login to Plex Media Center.

password: Password instance-attribute #

Password to use to login to Plex Media Center.

Plex Media Server#

Send media update notifications to a Plex Media Server instance.

Supported notification triggers: All except on_grab, on_health_issue and on_application_update

type: Literal['plex-media-server'] = 'plex-media-server' class-attribute instance-attribute #

Type value associated with this kind of connection.

host: NonEmptyStr instance-attribute #

Plex Media Server hostname or IP address.

port: Port = 32400 class-attribute instance-attribute #

Plex Media Server API port.

use_ssl: bool = False class-attribute instance-attribute #

Connect to Plex Media Server over HTTPS instead of HTTP.

auth_token: Password instance-attribute #

Plex authentication token.

If unsure on where to find this token, follow this guide from Plex.tv.

update_library: bool = True class-attribute instance-attribute #

Update the Plex Media Server library on import, rename or delete.

Prowl#

Send media update and health alert push notifications to a Prowl client.

Supported notification triggers: All except on_rename

type: Literal['prowl'] = 'prowl' class-attribute instance-attribute #

Type value associated with this kind of connection.

api_key: Password instance-attribute #

API key to use when authenticating with Prowl.

priority: ProwlPriority = ProwlPriority.normal class-attribute instance-attribute #

Prowl push notification priority.

Values:

  • verylow
  • low
  • normal
  • high
  • emergency

Pushbullet#

Send media update and health alert push notifications to 1 or more Pushbullet devices.

Supported notification triggers: All except on_rename

type: Literal['pushbullet'] = 'pushbullet' class-attribute instance-attribute #

Type value associated with this kind of connection.

api_key: Password instance-attribute #

API key to use when authenticating with Pushbullet.

device_ids: List[NonEmptyStr] = [] class-attribute instance-attribute #

List of device IDs to send notifications to.

If unset or empty, send to all devices.

channel_tags: List[NonEmptyStr] = [] class-attribute instance-attribute #

List of Channel Tags to send notifications to.

sender_id: Optional[str] = None class-attribute instance-attribute #

The device ID to send notifications from (device_iden in the device's URL on pushbullet.com).

Leave unset, blank or set to None to send from yourself.

Pushover#

Send media update and health alert push notifications to 1 or more Pushover devices.

Supported notification triggers: All except on_rename

type: Literal['pushover'] = 'pushover' class-attribute instance-attribute #

Type value associated with this kind of connection.

user_key: Annotated[SecretStr, Field(min_length=30, max_length=30)] instance-attribute #

User key to use to authenticate with your Pushover account.

api_key: Annotated[SecretStr, Field(min_length=30, max_length=30)] instance-attribute #

API key assigned to Sonarr in Pushover.

devices: Set[NonEmptyStr] = set() class-attribute instance-attribute #

List of device names to send notifications to.

If unset or empty, send to all devices.

priority: PushoverPriority = PushoverPriority.normal class-attribute instance-attribute #

Pushover push notification priority.

Values:

  • silent
  • quiet
  • normal
  • high
  • emergency
retry: Union[Literal[0], PushoverRetry] = 0 class-attribute instance-attribute #

Interval to retry emergency alerts, in seconds.

Minimum 30 seconds. Set to 0 to disable retrying emergency alerts.

expire: int = Field(0, ge=0, le=86400) class-attribute instance-attribute #

Threshold for retrying emergency alerts, in seconds. If retry is set, this should be set to a higher value.

Maximum 86400 seconds (1 day).

sound: Optional[str] = None class-attribute instance-attribute #

Notification sound to use on devices.

Leave unset, blank or set to None to use the default.

SendGrid#

Send media update and health alert emails via the SendGrid delivery service.

Supported notification triggers: All except on_rename

type: Literal['sendgrid'] = 'sendgrid' class-attribute instance-attribute #

Type value associated with this kind of connection.

api_key: Password instance-attribute #

API key to use to authenticate with SendGrid.

from_address: EmailStr instance-attribute #

Email address to send the mail as.

Changed in version 0.5.3: Disallow RFC-5322 formatted mailbox addresses (e.g. Sonarr Notifications <sonarr@example.com>), as they are not supported by Sonarr V3 (the currently supported version).

recipient_addresses: Annotated[List[EmailStr], Field(min_items=1, unique_items=True)] instance-attribute #

The recipient email addresses of the notification mail.

At least one recipient address is required.

Changed in version 0.5.3: Disallow RFC-5322 formatted mailbox addresses (e.g. Sonarr Notifications <sonarr@example.com>), as they are not supported by Sonarr V3 (the currently supported version).

Slack#

Send media update and health alert messages to a Slack channel.

Supported notification triggers: All

type: Literal['slack'] = 'slack' class-attribute instance-attribute #

Type value associated with this kind of connection.

webhook_url: AnyHttpUrl instance-attribute #

Webhook URL for the Slack channel to send to.

username: NonEmptyStr instance-attribute #

Username to post as.

icon: Optional[str] = None class-attribute instance-attribute #

The icon that is used for messages from this integration (emoji or URL).

If unset, blank or set to None, use the default for the user.

channel: Optional[str] = None class-attribute instance-attribute #

If set, overrides the default channel in the webhook.

Synology Indexer#

Send media update notifications to the local Synology Indexer.

Supported notification triggers: All except on_grab, on_health_issue and on_application_update

type: Literal['synology-indexer'] = 'synology-indexer' class-attribute instance-attribute #

Type value associated with this kind of connection.

update_library: bool = True class-attribute instance-attribute #

Update the library on media import/rename/delete.

Telegram#

Send media update and health alert messages to a Telegram chat room.

Supported notification triggers: All

type: Literal['telegram'] = 'telegram' class-attribute instance-attribute #

Type value associated with this kind of connection.

bot_token: Password instance-attribute #

The bot token assigned to the Sonarr instance.

chat_id: NonEmptyStr instance-attribute #

The ID of the chat room to send messages to.

You must start a conversation with the bot or add it to your group to receive messages.

send_silently: bool = False class-attribute instance-attribute #

Sends the message silently. Users will receive a notification with no sound.

Trakt#

Send media update and health alert messages to the Trakt media tracker.

Note

Sonarr directly authenticates with Trakt to generate tokens for it to use. At the moment, the easiest way to generate the tokens for Buildarr is to do it using the GUI within Sonarr, and use the following shell command to retrieve the generated configuration.

$ curl -X "GET" "<sonarr-url>/api/v3/notification" -H "X-Api-Key: <api-key>"

Supported notification triggers: All except on_grab, on_rename, on_health_issue and on_application_update

type: Literal['trakt'] = 'trakt' class-attribute instance-attribute #

Type value associated with this kind of connection.

access_token: Password instance-attribute #

Access token for Sonarr from Trakt.

refresh_token: Password instance-attribute #

Refresh token for Sonarr from Trakt.

expires: datetime instance-attribute #

Expiry date-time of the access token, preferably in ISO-8601 format and in UTC.

Example: 2023-05-10T15:34:08.117451Z

auth_user: TraktAuthUser instance-attribute #

The username being authenticated in Trakt.

Twitter#

Send media update and health alert messages via Twitter.

Twitter requires you to create an application for their API to generate the necessary keys and secrets. If unsure how to proceed, refer to these guides from Twitter and WikiArr.

Access tokens can be obtained using the prodecure documented here.

Supported notification triggers: All except on_rename

type: Literal['twitter'] = 'twitter' class-attribute instance-attribute #

Type value associated with this kind of connection.

consumer_key: Password instance-attribute #

Consumer key from a Twitter application.

consumer_secret: Password instance-attribute #

Consumer key from a Twitter application.

access_token: Password instance-attribute #

Access token for a Twitter user.

access_token_secret: Password instance-attribute #

Access token secret for a Twitter user.

mention: NonEmptyStr instance-attribute #

Mention this user in sent tweets.

direct_message: bool = True class-attribute instance-attribute #

Send a direct message instead of a public message.

Webhook#

Send media update and health alert notifications to a webhook API.

Supported notification triggers: All

type: Literal['webhook'] = 'webhook' class-attribute instance-attribute #

Type value associated with this kind of connection.

method: WebhookMethod = WebhookMethod.POST class-attribute instance-attribute #

HTTP request method type to use.

Values:

  • POST
  • PUT
username: NonEmptyStr instance-attribute #

Webhook API username.

password: Password instance-attribute #

Webhook API password.