Add a Microsoft 365 Graph Email Backend

[Luke-Sanborn]

This pull request adds an email backend using the Microsoft Authentication Library (MSAL). Microsoft 365 is phasing out Basic SMTP authentication. This will allow GeoNode users that uses Microsoft 365 to continue using email notifications within GeoNode.

This PR is mostly a rework of an existing pull request #12907

Checklist

Reviewing is a process done by project maintainers, mostly on a volunteer basis. We try to keep the overhead as small as possible and appreciate if you help us to do so by completing the following items. Feel free to ask in a comment if you have troubles with any of them.

For all pull requests:

• Confirm you have read the contribution guidelines
• You have sent a Contribution Licence Agreement (CLA) as necessary (not required for small changes, e.g., fixing typos in the documentation)
• Make sure the first PR targets the master branch, eventual backports will be managed later. This can be ignored if the PR is fixing an issue that only happens in a specific branch, but not in newer ones.

The following are required only for core and extension modules (they are welcomed, but not required, for contrib modules):

• There is a ticket in https://github.com/GeoNode/geonode/issues describing the issue/improvement/feature (a notable exemption is, changes not visible to end-users)
• The issue connected to the PR must have Labels and Milestone assigned
• PR for bug fixes and small new features are presented as a single commit
• PR title must be in the form "[Fixes #<issue_number>] Title of the PR"
• New unit tests have been added covering the changes, unless there is an explanation on why the tests are not necessary/implemented

Submitting the PR does not require you to check all items, but by the time it gets merged, they should be either satisfied or inapplicable.

[cla-bot]

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have the users @Luke-Sanborn on file. In order for us to review and merge your code, please contact the project maintainers to get yourself added.

[gemini-code-assist]

Code Review

This pull request introduces a new Django email backend, MicrosoftGraphEmailBackend, to send emails via the Microsoft Graph sendMail API, along with configuration options, documentation, and unit tests. The review feedback highlights several critical improvements: parsing the bare email address from mail_from to prevent invalid API URLs when a display name is present, enhancing the _send method to support HTML alternatives, attachments, and custom headers, fixing the saveToSentItems parameter to be a boolean, and utilizing requests.Session to reuse connections and reduce latency when sending multiple emails.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If EMAIL_MS_GRAPH_FROM is not set, it falls back to DEFAULT_FROM_EMAIL. In GeoNode, DEFAULT_FROM_EMAIL often contains a display name (e.g., 'GeoNode <no-reply@geonode.org>'). However, the Microsoft Graph API {mailbox} URL parameter requires a bare email address. Passing a display name formatted email address will result in an invalid URL and API failure. We should parse the bare email address using email.utils.parseaddr to prevent this.

    def _get_access_token(self):
        """
        Return ``(creds, token)`` or raise. Validates settings and acquires a Graph token.
        """
        creds = getattr(settings, "MICROSOFT_GRAPH_API_CREDENTIALS", {}) or {}
        missing = [k for k in ("tenant_id", "client_id", "client_secret", "mail_from") if not creds.get(k)]
        if missing:
            raise ImproperlyConfigured(f"MICROSOFT_GRAPH_API_CREDENTIALS is missing required keys: {missing}")

        # Extract bare email address in case it contains a display name (e.g. "Name <email@domain.com>")
        from email.utils import parseaddr
        mail_from = parseaddr(creds["mail_from"])[1]
        if not mail_from:
            raise ImproperlyConfigured(f"MICROSOFT_GRAPH_API_CREDENTIALS['mail_from'] is not a valid email address: {creds['mail_from']}")

        creds = creds.copy()
        creds["mail_from"] = mail_from

        if self._msal_app is None:
            self._msal_app = msal.ConfidentialClientApplication(
                client_id=creds["client_id"],
                client_credential=creds["client_secret"],
                authority=f"https://login.microsoftonline.com/{creds['tenant_id']}",
                token_cache=msal.SerializableTokenCache(),
            )

        result = self._msal_app.acquire_token_silent(
            GRAPH_TOKEN_SCOPE, account=None
        ) or self._msal_app.acquire_token_for_client(scopes=GRAPH_TOKEN_SCOPE)
        token = (result or {}).get("access_token")
        if not token:
            error = (result or {}).get("error_description", "no result from MSAL")
            raise RuntimeError(f"Microsoft Graph token acquisition failed: {error}")
        return creds, token

[gemini-code-assist]

This suggestion enhances the _send method to:

1. Support requests.Session for connection reuse.
2. Support EmailMultiAlternatives by automatically extracting the HTML alternative if the main body is plain text.
3. Support email attachments by encoding them to base64 and forwarding them to the Graph API.
4. Support custom email headers via internetMessageHeaders.
5. Fix saveToSentItems to be a proper JSON boolean (True) instead of a string ('true').

    def _send(self, message, token, creds, session=None):
        """
        Send a single email using Microsoft Graph API.
        """
        content_type = "HTML" if getattr(message, "content_subtype", "plain") == "html" else "Text"
        body_content = message.body

        # Handle EmailMultiAlternatives by looking for an HTML alternative
        if content_type == "Text" and hasattr(message, "alternatives"):
            for alternative in message.alternatives:
                if len(alternative) >= 2 and alternative[1] == "text/html":
                    body_content = alternative[0]
                    content_type = "HTML"
                    break

        payload = {
            "message": {
                "subject": message.subject,
                "body": {"contentType": content_type, "content": body_content},
                "toRecipients": [{"emailAddress": {"address": addr}} for addr in message.to],
                "ccRecipients": [{"emailAddress": {"address": addr}} for addr in message.cc],
                "bccRecipients": [{"emailAddress": {"address": addr}} for addr in message.bcc],
            },
            "saveToSentItems": True,
        }
        if message.reply_to:
            payload["message"]["replyTo"] = [{"emailAddress": {"address": addr}} for addr in message.reply_to]

        # Handle extra headers
        if getattr(message, "extra_headers", None):
            payload["message"]["internetMessageHeaders"] = [
                {"name": k, "value": str(v)} for k, v in message.extra_headers.items()
            ]

        # Handle attachments
        attachments = []
        for attachment in getattr(message, "attachments", []):
            if isinstance(attachment, tuple):
                filename, content, mimetype = attachment
            else:
                filename = attachment.get_filename() or "attachment"
                content = attachment.get_payload(decode=True)
                mimetype = attachment.get_content_type()

            if content is None:
                continue

            if isinstance(content, str):
                content = content.encode("utf-8")

            import base64
            content_bytes = base64.b64encode(content).decode("utf-8")
            attachments.append({
                "@odata.type": "#microsoft.graph.fileAttachment",
                "name": filename,
                "contentType": mimetype,
                "contentBytes": content_bytes,
            })
        if attachments:
            payload["message"]["attachments"] = attachments

        post_func = session.post if session else requests.post
        response = post_func(
            GRAPH_SENDMAIL_ENDPOINT.format(mailbox=creds["mail_from"]),
            headers={"Authorization": f

[gemini-code-assist]

When sending multiple emails in a batch, establishing a new TCP and TLS connection for each request introduces significant latency. We can use a requests.Session to reuse the underlying connection across requests, improving performance.

    def send_messages(self, email_messages):
        """
        Send multiple email messages using Microsoft Graph API.
        """
        if not email_messages:
            return 0
        try:
            creds, token = self._get_access_token()
        except Exception:
            if not self.fail_silently:
                raise
            logger.exception("Microsoft Graph token acquisition failed")
            return 0

        sent = 0
        with requests.Session() as session:
            for message in email_messages:
                try:
                    self._send(message, token, creds, session=session)
                    sent += 1
                except Exception:
                    if not self.fail_silently:
                        raise
                    logger.exception("Microsoft Graph sendMail failed for %s", message.to)
        return sent