mail: adding capability to specify ehlo hostname (#3425)

* Adding capability to specify ehlo hostname

* Fixing default for ehlohost

the CI did not like "None" as default in the documentation,
judging from the rest of the definitions omitting that seems to be right

* Update plugins/modules/notification/mail.py

Proper spelling in documentation

Co-authored-by: Ajpantuso <ajpantuso@gmail.com>

* Adding Changelog Fragment

* Update changelogs/fragments/3425-mail_add_configurable_ehlo_hostname.yml

Proper phrasing in changelog

Co-authored-by: Ajpantuso <ajpantuso@gmail.com>

* integration-test for ehlohost parameter

* proper description, increased async-time

changed body of ehlohost-mail to reflect ehlohost
increased async from 30 to 45 as CI failed because
smtp was already down.

Co-authored-by: Ajpantuso <ajpantuso@gmail.com>

changelogs/fragments/3425-mail_add_configurable_ehlo_hostname.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - mail - added the ``ehlohost`` parameter which allows for manual override of the host used in SMTP EHLO (https://github.com/ansible-collections/community.general/pull/3425).

plugins/modules/notification/mail.py

@@ -125,6 +125,11 @@ options:
     - Sets the timeout in seconds for connection attempts.
     type: int
     default: 20
+  ehlohost:
+    description:
+    - Allows for manual specification of host for EHLO.
+    type: str
+    version_added: 3.8.0
 '''
 
 EXAMPLES = r'''
@@ -189,6 +194,16 @@ EXAMPLES = r'''
     subject: Ansible-report
     body: System {{ ansible_hostname }} has been successfully provisioned.
     secure: starttls
+
+- name: Sending an e-mail using StartTLS, remote server, custom EHLO
+  community.general.mail:
+    host: some.smtp.host.tld
+    port: 25
+    ehlohost: my-resolvable-hostname.tld
+    to: John Smith <john.smith@example.com>
+    subject: Ansible-report
+    body: System {{ ansible_hostname }} has been successfully provisioned.
+    secure: starttls
 '''
 
 import os
@@ -215,6 +230,7 @@ def main():
             password=dict(type='str', no_log=True),
             host=dict(type='str', default='localhost'),
             port=dict(type='int', default=25),
+            ehlohost=dict(type='str', default=None),
             sender=dict(type='str', default='root', aliases=['from']),
             to=dict(type='list', elements='str', default=['root'], aliases=['recipients']),
             cc=dict(type='list', elements='str', default=[]),
@@ -235,6 +251,7 @@ def main():
     password = module.params.get('password')
     host = module.params.get('host')
     port = module.params.get('port')
+    local_hostname = module.params.get('ehlohost')
     sender = module.params.get('sender')
     recipients = module.params.get('to')
     copies = module.params.get('cc')
@@ -259,9 +276,9 @@ def main():
         if secure != 'never':
             try:
                 if PY3:
-                    smtp = smtplib.SMTP_SSL(host=host, port=port, timeout=timeout)
+                    smtp = smtplib.SMTP_SSL(host=host, port=port, local_hostname=local_hostname, timeout=timeout)
                 else:
-                    smtp = smtplib.SMTP_SSL(timeout=timeout)
+                    smtp = smtplib.SMTP_SSL(local_hostname=local_hostname, timeout=timeout)
                 code, smtpmessage = smtp.connect(host, port)
                 secure_state = True
             except ssl.SSLError as e:
@@ -273,9 +290,9 @@ def main():
 
         if not secure_state:
             if PY3:
-                smtp = smtplib.SMTP(host=host, port=port, timeout=timeout)
+                smtp = smtplib.SMTP(host=host, port=port, local_hostname=local_hostname, timeout=timeout)
             else:
-                smtp = smtplib.SMTP(timeout=timeout)
+                smtp = smtplib.SMTP(local_hostname=local_hostname, timeout=timeout)
             code, smtpmessage = smtp.connect(host, port)
 
     except smtplib.SMTPException as e:

tests/integration/targets/mail/tasks/main.yml

@@ -26,7 +26,7 @@
 #        This would require either dumping the content, or registering async task output
 - name: Start test smtpserver
   shell: '{{ ansible_python.executable }} {{ remote_tmp_dir }}/smtpserver.py 10025:10465'
-  async: 30
+  async: 45
   poll: 0
   register: smtpserver
 
@@ -88,3 +88,13 @@
 - fail:
     msg: Send mail using TLS failed.
   when: smtpd_tls is succeeded and tls_support is failed and starttls_support is succeeded
+
+- name: Send a test-mail with body, specific recipient and specific ehlohost
+  mail:
+    port: 10025
+    ehlohost: some.domain.tld
+    from: ansible@localhost
+    to: root@localhost
+    subject: Test mail 6 (smtp + body + ehlohost)
+    body: Test body 6
+    secure: never