mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-06-01 15:56:49 +00:00
121 lines
3.7 KiB
Markdown
121 lines
3.7 KiB
Markdown
---
|
|
title: Mailgun
|
|
description: Instructions on how to add Mailgun mail notifications to Home Assistant.
|
|
ha_category:
|
|
- Notifications
|
|
ha_release: 0.38
|
|
ha_config_flow: true
|
|
ha_domain: mailgun
|
|
---
|
|
|
|
To be able to receive webhooks from Mailgun, your Home Assistant instance needs to be accessible from the web and you need to have the extern URL [configured](/docs/configuration/basic)).
|
|
|
|
To set it up, go to the integrations page in the configuration screen and find Mailgun. Click on configure. Follow the instructions on the screen to configure Mailgun.
|
|
|
|
You will get a URL of the following format: `https://<home-assistant-domain>/api/webhook/9940e99a26fae4dcf6fe0a478124b6b58b578ea4c55c9a584beb1c9f5057bb91`. To receive webhooks from Mailgun, you need to provide that URL as a callback URL in the Webhooks tab of the Mailgun Control Panel.
|
|
|
|
There is currently support for the following device types within Home Assistant:
|
|
|
|
- [Notifications](#notifications).
|
|
|
|
## Configuration
|
|
|
|
```yaml
|
|
# Example configuration.yaml entry
|
|
mailgun:
|
|
domain: EXAMPLE.COM
|
|
api_key: YOUR_API_KEY
|
|
```
|
|
|
|
{% configuration %}
|
|
domain:
|
|
description: This is the domain name to be used when sending out mail. Needs to be the first custom domain you have set up.
|
|
required: true
|
|
type: string
|
|
api_key:
|
|
description: This is the API token that has been generated in your Mailgun account.
|
|
required: true
|
|
type: string
|
|
sandbox:
|
|
description: "(**Deprecated**) Whether to use the sandboxed domain for outgoing mail. Since the `domain` item is required, it should be set to the sandbox domain name, so this isn't needed."
|
|
required: false
|
|
default: false
|
|
type: boolean
|
|
{% endconfiguration %}
|
|
|
|
Events coming in from Mailgun will be available as events in Home Assistant and are fired as `mailgun_message_received`. The [data specified by Mailgun](https://documentation.mailgun.com/en/latest/api-events.html#event-structure) will be available as the event data. You can use this event to trigger automations.
|
|
|
|
You can then consume that information with the following automation:
|
|
|
|
```yaml
|
|
automation:
|
|
trigger:
|
|
platform: event
|
|
event_type: mailgun_message_received
|
|
event_data:
|
|
action: call_service
|
|
action:
|
|
service: light.turn_on
|
|
entity_id: light.office
|
|
```
|
|
|
|
## Notifications
|
|
|
|
The Mailgun notification service allows you to send emails via Mailgun's REST API. It requires the [Mailgun component](#configuration) to be set up.
|
|
|
|
### Notifications configuration
|
|
|
|
```yaml
|
|
# Example configuration.yaml entry
|
|
notify:
|
|
- name: mailgun
|
|
platform: mailgun
|
|
recipient: CHANGE@EXAMPLE.COM
|
|
```
|
|
|
|
{% configuration %}
|
|
domain:
|
|
description: This is the domain name to be used when sending out mail.
|
|
required: true
|
|
type: string
|
|
sandbox:
|
|
description: "(**Deprecated**) If a sandboxed domain is used, specify it in `domain`."
|
|
required: false
|
|
default: false
|
|
type: boolean
|
|
api_key:
|
|
description: This is the API Key that has been generated in your Mailgun account.
|
|
required: true
|
|
type: string
|
|
recipient:
|
|
description: The email address of the recipient.
|
|
required: true
|
|
type: string
|
|
sender:
|
|
description: The sender's email address.
|
|
required: false
|
|
default: "`hass@DOMAIN`, where `DOMAIN` is the outgoing mail domain, as defined by the `domain` configuration entry."
|
|
type: string
|
|
{% endconfiguration %}
|
|
|
|
### Example automation
|
|
|
|
The following automation reacts to an event by sending out an email with two attachments.
|
|
|
|
```yaml
|
|
# Example automation using Mailgun notifications
|
|
automation:
|
|
trigger:
|
|
platform: event
|
|
event_type: SPECIAL_EVENT
|
|
action:
|
|
service: notify.mailgun
|
|
data:
|
|
title: "Something special has happened"
|
|
message: "This a test message from Home Assistant"
|
|
data:
|
|
images:
|
|
- /home/pi/pic_test1.png
|
|
- /home/pi/pic_test2.png
|
|
```
|