# salt.returners.smtp_return

Return salt data via email

The following fields can be set in the minion conf file. Fields are optional unless noted otherwise.

- `from` (required) The name/address of the email sender.

- `to` (required) The names/addresses of the email recipients;

    comma-delimited. For example: `you@example.com,someoneelse@example.com`.

- `host` (required) The SMTP server hostname or address.

- `port` The SMTP server port; defaults to `25`.

- `username` The username used to authenticate to the server. If specified a

    password is also required. It is recommended but not required to also use TLS with this option.

- `password` The password used to authenticate to the server.

- `tls` Whether to secure the connection using TLS; defaults to `False`

- `subject` The email subject line.

- `fields` Which fields from the returned data to include in the subject line

    of the email; comma-delimited. For example: `id,fun`. Please note, the subject line is not encrypted.

- `gpgowner` A user's `~/.gpg` directory. This must contain a gpg

    public key matching the address the mail is sent to. If left unset, no encryption will be used. Requires python-gnupg to be installed.

- `template` The path to a file to be used as a template for the email body.

- `renderer` A Salt renderer, or render-pipe, to use to render the email

    template. Default `jinja`.

Below is an example of the above settings in a Salt Minion configuration file:

    smtp.from: me@example.net
    smtp.to: you@example.com
    smtp.host: localhost
    smtp.port: 1025

Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location. For example:

    alternative.smtp.username: saltdev
    alternative.smtp.password: saltdev
    alternative.smtp.tls: True

To use the SMTP returner, append '--return smtp' to the `salt` command.

    salt '*' test.ping --return smtp

To use the alternative configuration, append '--return_config alternative' to the `salt` command.

Added in version 2015.5.0.

    salt '*' test.ping --return smtp --return_config alternative

To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the `salt` command.

Added in version 2016.3.0.

    salt '*' test.ping --return smtp --return_kwargs '{"to": "user@domain.com"}'

An easy way to test the SMTP returner is to use the development SMTP server built into Python. The command below will start a single-threaded SMTP server that prints any email it receives to the console.

    python -m smtpd -n -c DebuggingServer localhost:1025

Added in version 2016.11.0.

It is possible to send emails with selected Salt events by configuring `event_return` option for Salt Master. For example:

    event_return: smtp

    event_return_whitelist:
      - salt/key

    smtp.from: me@example.net
    smtp.to: you@example.com
    smtp.host: localhost
    smtp.subject: 'Salt Master {{act}}ed key from Minion ID: {{id}}'
    smtp.template: /srv/salt/templates/email.j2

Also you need to create additional file `/srv/salt/templates/email.j2` with email body template:

    act: {{act}}
    id: {{id}}
    result: {{result}}

This configuration enables Salt Master to send an email when accepting or rejecting minions keys.

salt.returners.smtp_return.event_return(events)

  Return event data via SMTP

salt.returners.smtp_return.prep_jid(nocache=False, passed_jid=None)

  Do any work necessary to prepare a JID, including sending a custom id

salt.returners.smtp_return.returner(ret)

  Send an email with the data