mail - Send an email

Synopsis

  • This module is useful for sending emails from playbooks.
  • One may wonder why automate sending emails? In complex environments there are from time to time processes that cannot be automated, either because you lack the authority to make it so, or because not everyone agrees to a common approach.
  • If you cannot automate a specific step, but the step is non-blocking, sending out an email to the responsible party to make him perform his part of the bargain is an elegant way to put the responsibility in someone else’s lap.
  • Of course sending out a mail can be equally useful as a way to notify one or more people in a team that a specific action has been (successfully) taken.

Options

parameter required default choices comments
attach
 no
A space-separated list of pathnames of files to attach to the message. Attached files will have their content-type set to application/octet-stream.
bcc
 no
The email-address(es) the mail is being 'blind' copied to. This is a comma-separated list, which may contain address and phrase portions.
body
 no $subject
The body of the email being sent.
cc
 no
The email-address(es) the mail is being copied to. This is a comma-separated list, which may contain address and phrase portions.
charset
 no us-ascii
The character set of email being sent
from
 no root
The email-address the mail is sent from. May contain address and phrase.
headers
 no
A vertical-bar-separated list of headers which should be added to the message. Each individual header is specified as header=value (see example below).
host
 no localhost
The mail server
password
(added in 1.9)
 no
If SMTP requires password
port
 no 25
The mail server port. This must be a valid integer between 1 and 65534
secure
(added in 2.3)
 no try
  • always
  • never
  • try
  • starttls
If always, the connection will only send email if the connection is Encrypted. If the server doesn't accept the encrypted connection it will fail.
If try, the connection will attempt to setup a secure SSL/TLS session, before trying to send.
If never, the connection will not attempt to setup a secure SSL/TLS session, before sending
If starttls, the connection will try to upgrade to a secure SSL/TLS connection, before sending. If it is unable to do so it will fail.
subject
 yes
The subject of the email being sent.
subtype
(added in 2.0)
 no plain
The minor mime type, can be either text or html. The major type is always text.
timeout
(added in 2.3)
 no 20
Sets the Timeout in seconds for connection attempts
to
 no root
The email-address(es) the mail is being sent to. This is a comma-separated list, which may contain address and phrase portions.
username
(added in 1.9)
 no
If SMTP requires username

Examples

# Example playbook sending mail to root
- mail:
    subject: 'System {{ ansible_hostname }} has been successfully provisioned.'
  delegate_to: localhost

# Sending an e-mail using Gmail SMTP servers
- mail:
    host: smtp.gmail.com
    port: 587
    username: [email protected]
    password: mysecret
    to: John Smith <[email protected]>
    subject: Ansible-report
    body: 'System {{ ansible_hostname }} has been successfully provisioned.'
  delegate_to: localhost

# Send e-mail to a bunch of users, attaching files
- mail:
    host: 127.0.0.1
    port: 2025
    subject: Ansible-report
    body: Hello, this is an e-mail. I hope you like it ;-)
    from: [email protected] (Jane Jolie)
    to: John Doe <[email protected]>, Suzie Something <[email protected]>
    cc: Charlie Root <root@localhost>
    attach: /etc/group /tmp/pavatar2.png
    headers: '[email protected]|X-Special="Something or other"'
    charset: utf8
  delegate_to: localhost

# Sending an e-mail using the remote machine, not the Ansible controller node
- mail:
    host: localhost
    port: 25
    to: John Smith <[email protected]>
    subject: Ansible-report
    body: 'System {{ ansible_hostname }} has been successfully provisioned.'

# Sending an e-mail using Legacy SSL to the remote machine
- mail:
    host: localhost
    port: 25
    to: John Smith <[email protected]>
    subject: Ansible-report
    body: 'System {{ ansible_hostname }} has been successfully provisioned.'
    secure: always

 # Sending an e-mail using StartTLS to the remote machine
- mail:
    host: localhost
    port: 25
    to: John Smith <[email protected]>
    subject: Ansible-report
    body: 'System {{ ansible_hostname }} has been successfully provisioned.'
    secure: starttls

Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/mail_module.html