.. _emails: Email in CloudBolt #################### CloudBolt can send emails from a number of contexts, including management commands, recurring jobs, and your own custom plug-ins. To activate the sending of emails, configure the global SMTP settings at :guilabel:`Admin` -> :guilabel:`Email settings`. You will also be able to define a default 'From' address, as well as a CB Admin E-mail address to use as a default to receive failure reports. If the CB Admin Email field is set, the :guilabel:`Send Test Email` button will trigger an email to be sent, verifying the given SMTP settings. .. _email-templates: Customizing Email Templates =========================== To edit an existing Email Template, go to :guilabel:`Admin` -> :guilabel:`Email settings` and click on the pencil icon to the right of the template. For example: to remove the rate from the 'Order Complete' email, find the `Body` field and change this block: .. code-block:: html {% for server in order.prov_server_list %} * Hostname: {{ server.get_vm_name }}{% if server.ip %} Primary IP: {{ server.ip }} {% endif %}{% if server.rate %} Rate: {{ server.rate_display }}{% endif %} {% endfor%} To this: .. code-block:: html {% for server in order.prov_server_list %} * Hostname: {{ server.get_vm_name }}{% if server.ip %} Primary IP: {{ server.ip }} {% endif %} {% endfor%} Styling Emails ============== The `Body` field of each of the Email Templates are rendered within a base HTML template that adds a header image, footer link, and CSS styling. If an email is sent with the context of a particular request, it will be branded using the Portal associated with that request's domain. A header image and background color can be set for each Portal at :guilabel:`Admin` -> :guilabel:`Branded Portals`. Note: not all emails are sent with the context of a request. For instance, emails sent via the Job engine will use the default Portal. If the entire base email template needs to be overridden, that can be done by creating a file at `/var/opt/cloudbolt/proserv/templates/emailtemplates/base.html`. That template must contain a variable for `{{ email_body }}`, and an example would be: .. code-block:: html {% load helper_tags %} {{ email_body|safe|linebreaks }} Sent from {% portal_link %} Emails Sent Manually ==================== Via Plug-ins ```````````` Two helper methods are provided that make sending emails from within plug-ins easy. The first will send an email to the address used for the `CB Admin E-mail` setting. This can be useful when an error occurs that needs immediate attention. For generic emails, context should be provided with values for 'subject' and 'message' .. code-block:: python from utilities.mail import email_admin email_admin(context={'subject': 'Hello', 'message': 'My email message'}) To send mail using a specific email template, pass in the corresponding slug for that template: .. code-block:: python from utilities.mail import email_admin email_admin( slug='order-complete', context={ 'subject': 'Your order is complete', 'message': 'Success!', 'order': order, }, ) The context dictionary will be rendered in the email according to the Email Template's 'Subject', 'Body', and 'Text body' fields. The second method can send an email to any list of recipients. This could be useful for sending an email to the administrators of a group or the owner of a particular server. .. code-block:: python from utilities.mail import email email( recipients=[user1.email, user2.email], slug='expired-server', context={ 'subject': 'Your server is expiring', 'server': server, } ) If either of those methods fail, they will raise an InvalidConfigurationException. If the call should continue despite of any errors, use the `continue_on_error` argument to either method and they will log a warning but return successfully. .. code-block:: python from utilities.mail import email_admin email_admin( context={'subject': 'Not important'}, continue_on_error=True, ) Email Hook ```````````` One of the five built-in action types is "Email Hook". This action sends email to the provided recipients, usually provided by the context of where the hook was run. Like most action types, it can be configured to only run for specific groups, environments, or resource technologies. See :ref:`email-hooks` for more information. Emailing Reports ```````````````` Some reports provide an :guilabel:`Email Report` button that will send the report via email to a provided address. Emails Sent Automatically ========================= Management Commands ```````````````````` Various management commands, including `check_for_stale_jobs`, `quota_monitor` and `rates_monitor`, sends an email if the command fails. It sends then to any addresses provided via the ``--emails`` flag, otherwise it uses the global `CB Admin E-mail` address. The `export_server_info` command can deliver its report via email, either to a provided address via the ``--email-to`` flag, or to the global `CB Admin E-mail` address via the ``--email-group-admins`` flag. Job Engine ``````````` Several steps related to provisioning servers will send emails. This includes: - When an order is submitted for approval, an email is sent to the approvers for that order's Group. See :ref:`users-and-permissions` for more information. - The :guilabel:`Send Reminder` button on a job's detail page will also send an email to the approvers for that order's Group. - When an order is complete, an email is sent to that order's owner. - When an order with a recipient specified completes successfully, an email is sent to the recipient to notify them of any new servers and/or resources they own. - If a provision job fails, an email will be sent to the global `CB Admin E-mail` address. Other job types that send an email to the admin address if they fail include: - Synchronize VMs from Resource Handlers - Synchronize servers from Provision Engines - Continuous Infrastructure Testing Out-of-the-box Content that sends Email ======================================= Orchestration Actions `````````````````````` One orchestration action provided by CloudBolt that will send email is the "Email Owners of Expired Servers" action at the Pre-Expire Server hook point. It will send an email to the server's owner if one exists. See :ref:`cloudbolt_plugins` for more information. Rules `````` A generic Send Email action is used for several out-of-the-box rules. You can see it in action as the Then behavior for the `Notify admins when a newer version of CloudBolt is available` rule. Several other out-of-the-box rules also send emails. Some examples include: - "Email owners of AWS VMs Missing Required Tags": Given a list of AWS servers missing required tags, this sends an email to their owners. - "Expire Resources": This notifies resource owners that their resource has expired. If the resource has been expired for more than a certain number of days, a resource deletion job is also created. - "Email group admins when quota usage over threshold": Sends group quota warnings for each group with a quota violation. The email will be sent to all group members with the "Manage Subgroup Quotas" permission, so ensure that your group admins have this permission before using this action. See :ref:`rules-section` for more information.