---
title: Email (SMTP) event handler
description: The “email” event handler allows you to send Kapacitor alerts via email. This page includes configuration options and usage examples.
url: https://docs.influxdata.com/kapacitor/v1/reference/event_handlers/email/
estimated_tokens: 5114
product: Kapacitor
version: v1
---

# Email (SMTP) event handler

The Email event handler sends alert messages via SMTP/email.

## Configuration

Configuration as well as default [option](#options) values for the Email event handler are set in the `[smtp]` section of your `kapacitor.conf`. Below is an example configuration:

```toml
[smtp]
  enabled = true
  host = "localhost"
  port = 25
  username = "username"
  password = "passw0rd"
  from = "me@example.com"
  to = ["me@example.com", "you@example.com"]
  no-verify = false
  idle-timeout = "30s"
  global = false
  state-changes-only = false
```

#### `enabled`

Set to `true` to enable the SMTP event handler.

#### `host`

The SMTP host.

#### `port`

The SMTP port.

#### `username`

Your SMTP username.

#### `password`

Your SMTP password.

#### `from`

The “From” address for outgoing mail.

#### `to`

List of default “To” addresses.

#### `no-verify`

Skip TLS certificate verification when connecting to the SMTP server.

#### `idle-timeout`

The time after which idle connections are closed.

#### `global`

If `true`, all alerts will be sent via Email without explicitly specifying the SMTP handler in the TICKscript.

#### `state-changes-only`

Sets all alerts in state-changes-only mode, meaning alerts will only be sent if the alert state changes. Only applies if `global` is `true`.

## Options

The following Email event handler options can be set in a [handler file](/kapacitor/v1/reference/event_handlers/#create-a-topic-handler-with-a-handler-file) or when using `.email()` in a TICKscript.

| Name | Type | Description |
| --- | --- | --- |
| to | list of strings | List of email addresses. |
| toTemplate(s) | string template | Derived email addresses. |

### Example: handler file

```yaml
id: handler-id
topic: topic-name
kind: smtp
options:
  to:
    - oncall1@example.com
    - oncall2@example.com
```

### Example: TICKscript

```js
|alert()
  // ...
  .email()
    .to('oncall1@example.com')
    .to('oncall2@example.com')

  // OR
  .email('oncall1@example.com')
    .to('oncall2@example.com')
```

### Using the SMTP/Email event handler

The Email event handler can be used in both TICKscripts and handler files to email alerts. The email subject is the [AlertNode.Message](/kapacitor/v1/reference/nodes/alert_node/#message) property. The email body is the [AlertNode.Details](/kapacitor/v1/reference/nodes/alert_node/#details) property. The emails are sent as HTML emails so the body can contain html markup.

***SMTP settings in kapacitor.conf***

```toml
[smtp]
  enabled = true
  host = "smtp.myserver.com"
  port = 25
  username = "username"
  password = "passw0rd"
  from = "me@emyserver.com"
  to = ["oncall0@mydomain.com"]
  no-verify = false
  idle-timeout = "30s"
  global = false
  state-changes-only = false
```

### Email alerts from a TICKscript

The following TICKscript uses the `.email()` event handler to send out emails whenever idle CPU usage drops below 10%.

***email-cpu-alert.tick***

```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .message('Hey, check your CPU')
    .email()
      .to('oncall1@mydomain.com')
      .to('oncall2@mydomain.com')
```

### Email alerts from a defined handler

The following setup sends an alert to the `cpu` topic with the message, “Hey, check your CPU”. An email handler is added that subscribes to the `cpu` topic and emails all alerts.

Create a TICKscript that publishes alert messages to a topic. The TICKscript below sends an alert message to the `cpu` topic any time idle CPU usage drops below 10%.

***cpu\_alert.tick***

```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .message('Hey, check your CPU')
    .topic('cpu')
```

Add and enable the TICKscript:

```bash
kapacitor define cpu_alert -tick cpu_alert.tick
kapacitor enable cpu_alert
```

Create a handler file that subscribes to the `cpu` topic and uses the `email` or `smtp` event handler to email alerts.

***email\_cpu\_handler.yaml***

```yaml
id: email-cpu-alert
topic: cpu
kind: smtp
options:
  to:
    - oncall1@mydomain.com
    - oncall2@mydomain.com
```

Add the handler:

```bash
kapacitor define-topic-handler email_cpu_handler.yaml
```

### Send email alerts using the toTemplate option

You can use `toTemplate` to derive email addresses directly from data instead of hardcoding them individually. In the example below, we are using both the `to` option and `toTemplates` option in order to derive email addresses from a dataset and send email alerts directly to recipients. Like the `to` option, the `toTemplates` option can be used more than once in a TICKscript. You can combine the `to` and `toTemplates` options or use them individually depending on your use case.

```js
stream
	|from()
		.measurement('cpu')
		.where(lambda: "host" == 'serverA')
		.groupBy('host')
	|window()
		.period(10s)
		.every(10s)
	|count('value')
	|default()
		.field('extraemail','bob@example.com')
		.tag('tagemail','bob2@example.com')
	|alert()
		.id('kapacitor.{{ .Name }}.{{ index .Tags "host" }}')
		.details('''
<b>{{.Message}}</b>
Value: {{ index .Fields "count" }}
<a href="http://graphs.example.com/host/{{index .Tags "host"}}">Details</a>
''')
		.info(lambda: "count" > 6.0)
		.warn(lambda: "count" > 7.0)
		.crit(lambda: "count" > 8.0)
		.email()
			.to('user1@example.com', 'user2@example.com')
			.toTemplates('{{ index .Fields "extraemail" }}')
```