Metadata-Version: 2.4
Name: failmail
Version: 0.1.1
Summary: A Python package to notify users via email when exceptions occur.
Project-URL: Homepage, https://github.com/spyel/failmail
Project-URL: Issues, https://github.com/spyel/failmail/issues
License: MIT License
        
        Copyright (c) 2025 Spyel
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# ✉️ Failmail

`Failmail`  is a Python package designed to send email notifications when exceptions are raised in your application.
It offers an easy-to-use registry system to associate specific exceptions with customizable email alerts.
You can specify the recipients, subject, body, and format (plain-text or HTML) for the notifications. 

**Note: ``Failmail`` is in early development. The API may change as new features are added and refined.**


## 🌱 Getting Started

### 🔧 Installation

To install the package, run:

```bash
pip install failmail
```

For the latest development version directly from the repository, use:

```bash
pip install git+https://github.com/spyel/failmail.git
```

### 🖥️ Usage

First, create an instance of ``ExceptionNotifier`` and configure it with your SMTP server details:

```python
from failmail import ExceptionNotifier

# Set up the notifier with your SMTP server details
notifier = ExceptionNotifier(
    host=('smtp.example.com', 587),       # SMTP server address and port
    sender_email='sender@example.com',    # Sender's email address
    credentials=('username', 'password'), # SMTP login credentials (optional)
    encryption='tls'                      # Encryption type: 'tls' or 'ssl' or 'none'
)
```

Next, register specific exceptions along with their corresponding email notifications.
You can define the recipients, subject, body, and the format of the email (either ``plain`` or ``html``):

```python
notifier.register_exception(
    exception_type=ValueError,  # The exception to register
    recipients=['admin@example.com'],
    subject='Error: ${error_type} occurred',
    body='An error of type ${error_type} occurred at ${timestamp}.\n\nMessage: ${error_message}\n\nTraceback:\n${error_traceback}',
    body_type='plain'  # Use 'html' for HTML format
)
````

When an exception occurs, use the ``notify()`` method to send the email notification:

```python
try:
    # Some code that may raise an exception
    raise ValueError("Something went wrong!")
except Exception as e:
    # Notify recipients when an exception is raised
    notifier.notify(e)
````

You can also include additional context to customize the email notification.
This context will be used to format the subject and body of the email:

```python
additional_context = {
    'custom_info': 'Additional data for the notification'
}
notifier.notify(e, additional_context=additional_context)
```


## 📄 License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
