# sendgrid – Sends an email with the SendGrid API

- Synopsis

- Requirements

- Parameters

- Notes

- Examples

- Status

## Synopsis

- Sends an email with a SendGrid account through their API, not through the SMTP service.

## Requirements

The below requirements are needed on the host that executes this module.

- sendgrid python library

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
api_key - |  | sendgrid API key to use instead of username/password
attachments - |  | a list of relative or explicit paths of files you want to attach (7MB limit as per SendGrid docs)
bcc - |  | a list of email addresses to bcc
cc - |  | a list of email addresses to cc
from_address - / required |  | the address in the "from" field for the email
from_name - |  | the name you want to appear in the from field, i.e 'John Doe'
headers - |  | a dict to pass on as headers

html_body
boolean

Choices:
- no ←
- yes

whether the body is html content that should be rendered

password - |  | password that corresponds to the username Since 2.2 it is only required if api_key is not supplied.
subject - / required |  | the desired subject for the email
to_addresses - / required |  | a list with one or more recipient email addresses
username - |  | username for logging into the SendGrid account. Since 2.2 it is only required if api_key is not supplied.

## Notes

Note

- This module is non-idempotent because it sends an email through the external API. It is idempotent only in the case that the module fails.

- Like the other notification modules, this one requires an external dependency to work. In this case, you’ll need an active SendGrid 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

## Examples

    # send an email to a single recipient that the deployment was successful
    - sendgrid:
        username: "{{ sendgrid_username }}"
        password: "{{ sendgrid_password }}"
        from_address: "ansible@mycompany.com"
        to_addresses:
          - "ops@mycompany.com"
        subject: "Deployment success."
        body: "The most recent Ansible deployment was successful."
      delegate_to: localhost

    # send an email to more than one recipient that the build failed
    - sendgrid:
          username: "{{ sendgrid_username }}"
          password: "{{ sendgrid_password }}"
          from_address: "build@mycompany.com"
          to_addresses:
            - "ops@mycompany.com"
            - "devteam@mycompany.com"
          subject: "Build failure!."
          body: "Unable to pull source repository from Git server."
      delegate_to: localhost

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Matt Makai (@makaimc)

Hint

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