mail - Send an email

Synopsis

Parameters

Parameter Choices/Defaults Comments
attach Default:
[]
A list of pathnames of files to attach to the message.
Attached files will have their content-type set to application/octet-stream.
bcc
The email-address(es) the mail is being 'blind' copied to.
This is a list, which may contain address and phrase portions.
body Default:
$subject
The body of the email being sent.
cc
The email-address(es) the mail is being copied to.
This is a list, which may contain address and phrase portions.
charset Default:
utf-8
The character set of email being sent.
from Default:
root
The email-address the mail is sent from. May contain address and phrase.
headers Default:
[]
A list of headers which should be added to the message.
Each individual header is specified as header=value (see example below).
host Default:
localhost
The mail server.
password
(added in 1.9)
If SMTP requires password.
port Default:
25
The mail server port.
This must be a valid integer between 1 and 65534
secure
(added in 2.3)
    Choices:
  • always
  • never
  • starttls
  • try ←
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
required
The subject of the email being sent.
subtype
(added in 2.0)
    Choices:
  • html
  • plain ←
The minor mime type, can be either plain or html.
The major type is always text.
timeout
(added in 2.3)
Default:
20
Sets the timeout in seconds for connection attempts.
to Default:
root
The email-address(es) the mail is being sent to.
This is a list, which may contain address and phrase portions.

aliases: recipients
username
(added in 1.9)
If SMTP requires username.

Examples

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

- name: 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

- name: 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 <[email protected]>
    attach:
    - /etc/group
    - /tmp/avatar2.png
    headers:
    - [email protected]
    - X-Special="Something or other"
    charset: us-ascii
  delegate_to: localhost

- name: 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.

- name: 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

- name: 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.

Maintenance

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author

  • Dag Wieers (@dagwieers)

Hint

If you notice any issues in this documentation you can edit this document to improve it.