===============
Messaging
===============

E-mails
----------
E-mail messages are handled using SendGrid by default or an SMTP server in production.

1. SendGrid configuration
    To use Sendgrid as the mail client these env variables must be used:

    :envvar:`EMAIL_BACKEND` = ``'sendgrid_backend.SendgridBackend'``

    :envvar:`SENDGRID_API_KEY` = ``'<SENDGRID_API_KEY>'``

2. SMTP Server Configuration
    To use a dedicated SMTP server as the mail client these env variables must be used:

    :envvar:`EMAIL_BACKEND` = ``'django.core.mail.backends.smtp.EmailBackend'``

    :envvar:`EMAIL_HOST` = ``'smtp.megit.com'``

    :envvar:`EMAIL_PORT` = ``'465'``

    :envvar:`EMAIL_HOST_USER` = ``'noreply@megit.com'``

    :envvar:`EMAIL_HOST_PASSWORD` = ``'password'``

    :envvar:`EMAIL_USE_TLS` = ``False``

    :envvar:`EMAIL_USE_SSL` = ``False``

    :envvar:`EMAIL_TIMEOUT` = ``60``

3. SMTP Server Configuration via django admin
    It is possible to configure the SMTP server via django admin. The following env variable must be used:

    :envvar:`EMAIL_BACKEND` = ``'emails.backends.CustomSMTPBackend'``

    You can then configure the SMTP server in django admin `/meg-admin/emails/customsmtpbackendconfig`. It is possible to add multiple custom smtp backends via this model, but only one will be used for sending e-mail. The config with the lowest 'order' will be chosen.


In development all e-mails are printed to console.
To use sendgrid in development, set :envvar:`EMAIL_BACKEND` variable to ``'sendgrid_backend.SendgridBackend'``.


Sending e-mails
^^^^^^^^^^^^^^^^^
To send e-mail, use ``emails.utils.send_mail_template`` utility function. This method sends out e-mail message as rich and plain text, so both html and txt templates are needed.
Locale should be supplied to translate all lazy strings within subject and e-mail body.

Alternatively, ``send_simple_mail`` can be used to send a simple e-mail message to user without building bespoke template.
E-mails sent this way can contain text and a list of links.

Receiving e-mails
^^^^^^^^^^^^^^^^^^^
Ability to handle received e-mail is possible with SendGrid using `inbound parse webhook <https://docs.sendgrid.com/for-developers/parsing-email/setting-up-the-inbound-parse-webhook>`_.

Received e-mails are received by ``SendgridWebhookView`` and can be handled by connecting to ``email_received`` signal.

.. code-block:: python
    :caption: Sample signal receiver implementation

    def on_email_received(sender, *, email: EmailMessage, **kwargs):
        print(f"Received e-mail from {email.from_email}: {email.subject}")

.. note::
    The receiver will be triggered for every e-mail and must implement a way to filter-out irrelevant e-mails or spam.

.. seealso:: Setup process to configure inbound parse is documented in :ref:`setup-inbound-parse`

More details in the original :task:`26421`.

:term:`Push Messages <Push Message>`
--------------------------------------
Push messages are handled by `Urbanairship <https://go.urbanairship.com/>`_. Implemented in :task:`25879`.

The messages can be received by :term:`client app` or the :term:`eGuide` app, but the way they are set-up is different.

Client app
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:term:`Client app` push message functionality was implemented in :task:`24429`.

To send a push-message to :term:`client app`, use :func:`send_user_push_message()<push_messages.utils.send_user_push_message>` utility method.
API keys are defined by :envvar:`URBANAIRSHIP_APP_KEY` and :envvar:`URBANAIRSHIP_MASTER_SECRET`.

Test notification can be triggered by sending an `Instant Messaging`_ message to the user.
The client app uses hardcoded keys when targeting staging or production. When targeting local test server, it does not define
keys and cannot receive messages.

eGuide apps
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:term:`eGuide` apps define their own API keys and can be managed in :url:`admin </meg-admin/push_messages/pushmessageconfig/>`.
Admin provides the option to send a test push message to a single device (Channel ID in "About app" screen).

Instant Messaging
-------------------
Messaging can be set-up per institution by creating an ``InstitutionMessagingConfig`` object.
This enables the users ability to send and receive messages between user and other users or receive system messages.

Messages can be sent to user with :func:`send_system_message()<messaging.messaging.send_system_message>`. To send a templated message, similar to e-mail, use :func:`send_system_message_template()<messaging.messaging.send_system_message_template>`.

Sending a message triggers a `push notification <Push Messages>`_ on user's device.

.. automodule:: messaging.messaging
    :members:

.. uml:: ../../messaging.puml
    :caption: Overview diagram of the messaging system


SMS/Phone call
----------------
SMS and phone calls are handled by Twilio. Use ``TwilioClient`` to send messages to user's phone.

.. automodule:: megforms.notifications.twilio
    :members:

.. automodule:: megforms.notifications.twilio_notification
    :members: