Metadata-Version: 2.4
Name: azure_simple_email
Version: 0.3.0
Summary: This is an alpha library to send email using Microsoft Graph API, a Microsoft 365 account is required to use this library  
Home-page: https://github.com/marcotn/azure_simple_email
Author: Marco Pavanelli
Author-email: marco.pavanelli@sasabz.it
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: msal
Requires-Dist: requests
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# azure-simple-email

[![PyPI version](https://badge.fury.io/py/azure-simple-email.svg)](https://pypi.org/project/azure-simple-email/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)

A lightweight Python library for sending email through Microsoft Azure using
the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/overview).

It wraps the OAuth2 client-credentials flow (via
[MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-python))
and the Graph `sendMail` endpoint into a simple, reusable class — no boilerplate
required.

## Features

- Plain-text and HTML emails
- Multiple To / CC / BCC recipients
- File attachments (from disk or in-memory bytes)
- Reply-To header support
- Token caching — send multiple emails without re-authenticating
- Debug mode to redirect all outgoing mail to a test address

## Installation

```bash
pip install azure-simple-email
```

## Quick start

```python
from azure_simple_email import AzureSendMail

mailer = AzureSendMail(user_id="noreply@example.com")
mailer.add_recipient("alice@example.com")
mailer.send_email(subject="Hello", text="Hi Alice!")
```

## Configuration

The library reads credentials from three environment variables:

| Variable | Description |
|---|---|
| `AZURE_EMAIL_CLIENT_ID` | Azure AD application (client) ID |
| `AZURE_EMAIL_CLIENT_SECRET` | Azure AD client secret |
| `AZURE_EMAIL_CLIENT_AUTHORITY` | Authority URL, e.g. `https://login.microsoftonline.com/<tenant-id>` |

You can set them in a `.env` file and load it with
[python-dotenv](https://github.com/theskumar/python-dotenv), or export them
directly in your shell.

### Setting up the Azure app registration

1. Go to **Azure portal → Azure Active Directory → App registrations → New registration**.
2. Under **API permissions**, add **Microsoft Graph → Application permissions → Mail.Send**.
3. Click **Grant admin consent**.
4. Under **Certificates & secrets**, create a client secret and copy its value.

## Usage examples

### HTML email with attachment

```python
from azure_simple_email import AzureSendMail

mailer = AzureSendMail(user_id="noreply@example.com")
mailer.add_recipient("alice@example.com")
mailer.add_attachment("/path/to/report.pdf")
mailer.send_email(
    subject="Monthly report",
    text="<h1>Report</h1><p>Please find the report attached.</p>",
    content_type="HTML",
)
```

### Multiple recipients with CC and BCC

```python
mailer = AzureSendMail(user_id="noreply@example.com")
mailer.add_recipient("alice@example.com")
mailer.add_cc_recipient("bob@example.com")
mailer.add_bcc_recipient("audit@example.com")
mailer.send_email(subject="Update", text="Quarterly update.")
```

### Sending multiple emails (token reuse)

```python
mailer = AzureSendMail(user_id="noreply@example.com")

for address in ["alice@example.com", "bob@example.com"]:
    mailer.add_recipient(address)
    mailer.send_email(subject="Newsletter", text="Hello!")
    mailer.clear()  # resets recipients/attachments, keeps the token
```

See the [full documentation](https://github.com/marcotn/azure_simple_email) and
the [`examples/`](examples/) directory for more.

## Building the documentation locally

```bash
pip install -r docs/requirements.txt
sphinx-build -b html docs/ docs/_build/html
```

Then open `docs/_build/html/index.html` in your browser.

## License

MIT — see [LICENSE](LICENSE).
