ansible.builtin.mail (v2.4.6.0-1) — module

Install Ansible via pip

Install with pip install ansible==2.4.6.0.post1

Description

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.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 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: jane@example.net (Jane Jolie)
    to: John Doe <j.d@example.org>, Suzie Something <sue@example.com>
    cc: Charlie Root <root@localhost>
    attach: /etc/group /tmp/pavatar2.png
    headers: 'Reply-To=john@example.com|X-Special="Something or other"'
    charset: utf8
  delegate_to: localhost

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Inputs

    
cc:
    description:
    - The email-address(es) the mail is being copied to. This is a comma-separated list,
      which may contain address and phrase portions.
    required: false

to:
    default: root
    description:
    - The email-address(es) the mail is being sent to. This is a comma-separated list,
      which may contain address and phrase portions.
    required: false

bcc:
    description:
    - The email-address(es) the mail is being 'blind' copied to. This is a comma-separated
      list, which may contain address and phrase portions.
    required: false

body:
    default: $subject
    description:
    - The body of the email being sent.
    required: false

from:
    default: root
    description:
    - The email-address the mail is sent from. May contain address and phrase.
    required: false

host:
    default: localhost
    description:
    - The mail server
    required: false

port:
    default: 25
    description:
    - The mail server port.  This must be a valid integer between 1 and 65534
    required: false
    version_added: '1.0'
    version_added_collection: ansible.builtin

attach:
    default: null
    description:
    - A space-separated list of pathnames of files to attach to the message. Attached
      files will have their content-type set to C(application/octet-stream).
    required: false
    version_added: '1.0'
    version_added_collection: ansible.builtin

secure:
    choices:
    - always
    - never
    - try
    - starttls
    default: try
    description:
    - If C(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 C(try), the connection will attempt to setup a secure SSL/TLS session, before
      trying to send.
    - If C(never), the connection will not attempt to setup a secure SSL/TLS session,
      before sending
    - If C(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.
    required: false
    version_added: '2.3'
    version_added_collection: ansible.builtin

charset:
    default: us-ascii
    description:
    - The character set of email being sent
    required: false

headers:
    default: null
    description:
    - A vertical-bar-separated list of headers which should be added to the message. Each
      individual header is specified as C(header=value) (see example below).
    required: false
    version_added: '1.0'
    version_added_collection: ansible.builtin

subject:
    description:
    - The subject of the email being sent.
    required: true

subtype:
    default: plain
    description:
    - The minor mime type, can be either text or html. The major type is always text.
    required: false
    version_added: '2.0'
    version_added_collection: ansible.builtin

timeout:
    default: 20
    description:
    - Sets the Timeout in seconds for connection attempts
    required: false
    version_added: '2.3'
    version_added_collection: ansible.builtin

password:
    default: null
    description:
    - If SMTP requires password
    required: false
    version_added: '1.9'
    version_added_collection: ansible.builtin

username:
    default: null
    description:
    - If SMTP requires username
    required: false
    version_added: '1.9'
    version_added_collection: ansible.builtin