diff --git a/changelogs/fragments/1553_sendgrid.yml b/changelogs/fragments/1553_sendgrid.yml new file mode 100644 index 0000000000..9be912d2c5 --- /dev/null +++ b/changelogs/fragments/1553_sendgrid.yml @@ -0,0 +1,2 @@ +bugfixes: +- sendgrid - update documentation and warn user about sendgrid Python library version (https://github.com/ansible-collections/community.general/issues/1553). diff --git a/plugins/modules/notification/sendgrid.py b/plugins/modules/notification/sendgrid.py index a849297bc1..67132771c0 100644 --- a/plugins/modules/notification/sendgrid.py +++ b/plugins/modules/notification/sendgrid.py @@ -1,14 +1,14 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -# (c) 2015, Matt Makai +# Copyright: (c) 2015, Matt Makai # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: sendgrid short_description: Sends an email with the SendGrid API @@ -23,73 +23,73 @@ notes: account." - "In order to use api_key, cc, bcc, attachments, from_name, html_body, headers you must pip install sendgrid" - - "since 2.2 username and password are not required if you supply an api_key" + - "since 2.2 I(username) and I(password) are not required if you supply an I(api_key)" requirements: - - sendgrid python library + - sendgrid Python library 1.6.22 or lower (Sendgrid API V2 supported) options: username: type: str description: - - username for logging into the SendGrid account. - - Since 2.2 it is only required if api_key is not supplied. + - Username for logging into the SendGrid account. + - Since 2.2 it is only required if I(api_key) is not supplied. password: type: str description: - - password that corresponds to the username - - Since 2.2 it is only required if api_key is not supplied. + - Password that corresponds to the username. + - Since 2.2 it is only required if I(api_key) is not supplied. from_address: type: str description: - - the address in the "from" field for the email + - The address in the "from" field for the email. required: true to_addresses: type: list description: - - a list with one or more recipient email addresses + - A list with one or more recipient email addresses. required: true subject: type: str description: - - the desired subject for the email + - The desired subject for the email. required: true api_key: type: str description: - - sendgrid API key to use instead of username/password + - Sendgrid API key to use instead of username/password. cc: type: list description: - - a list of email addresses to cc + - A list of email addresses to cc. bcc: type: list description: - - a list of email addresses to bcc + - A list of email addresses to bcc. attachments: type: list description: - - a list of relative or explicit paths of files you want to attach (7MB limit as per SendGrid docs) + - A list of relative or explicit paths of files you want to attach (7MB limit as per SendGrid docs). from_name: type: str description: - - the name you want to appear in the from field, i.e 'John Doe' + - The name you want to appear in the from field, i.e 'John Doe'. html_body: description: - - whether the body is html content that should be rendered + - Whether the body is html content that should be rendered. type: bool default: 'no' headers: type: dict description: - - a dict to pass on as headers + - A dict to pass on as headers. body: type: str description: - - the e-mail body content + - The e-mail body content. required: yes author: "Matt Makai (@makaimc)" ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Send an email to a single recipient that the deployment was successful community.general.sendgrid: username: "{{ sendgrid_username }}" @@ -120,6 +120,8 @@ EXAMPLES = ''' import os import traceback +from distutils.version import LooseVersion + SENDGRID_IMP_ERR = None try: import sendgrid @@ -155,6 +157,9 @@ def post_sendgrid_api(module, username, password, from_address, to_addresses, 'Accept': 'application/json'} return fetch_url(module, SENDGRID_URI, data=encoded_data, headers=headers, method='POST') else: + # Remove this check when adding Sendgrid API v3 support + if LooseVersion(sendgrid.version.__version__) > LooseVersion("1.6.22"): + module.fail_json(msg="Please install sendgrid==1.6.22 or lower since module uses Sendgrid V2 APIs.") if api_key: sg = sendgrid.SendGridClient(api_key)