Metadata-Version: 2.4
Name: emailsenderutils
Version: 0.0.1
Summary: An EmailSender type and related utility functions
Author-email: Scott Karlin <pypi@karlin-online.com>
Maintainer-email: Scott Karlin <pypi@karlin-online.com>
License-Expression: MIT
Project-URL: homepage, https://gitlab.com/sck/emailsenderutils
Project-URL: bugs, https://gitlab.com/sck/emailsenderutils/-/issues
Project-URL: changelog, https://gitlab.com/sck/emailsenderutils/-/blob/main/HISTORY.md
Project-URL: documentation, https://sck.gitlab.io/emailsenderutils/
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: attrs>=25.3.0
Dynamic: license-file

# Email Sender Utils

![PyPI version](https://img.shields.io/pypi/v/emailsenderutils.svg)

An EmailSender type and related utility functions

* Created by **[Scott Karlin](https://gitlab.com/sck)**
  * GitLab: https://gitlab.com/sck
  * PyPI: https://pypi.org/user/sckarlin/

## Project links

* **PyPI:** https://pypi.org/project/emailsenderutils/
* **Documentation:** https://sck.gitlab.io/emailsenderutils/
* **Source & issues:** https://gitlab.com/sck/emailsenderutils

## Features

* `build_message()` — assemble a `email.message.EmailMessage` from
  addresses, headers, a body, and optional text/PDF/WAV attachments.
* `mailsend()` — send a prepared message over SMTP, with optional
  STARTTLS and authentication.

## Usage

```python
import emailsenderutils

msg = emailsenderutils.build_message(
    fromaddr='me@example.com',
    toaddr_list=['dest@example.com', 'bcc@example.com'],
    fromline='My Name <me@example.com>',
    toline='My Destination <dest@example.com>',
    subjline='The Subject',
    body='The message body',
)
```

## Documentation

* **Live site:** https://sck.gitlab.io/emailsenderutils/
* **Preview locally:** `make docs-serve` (serves at http://localhost:8000)

API documentation is auto-generated from docstrings.

## Development

To set up for local development:

```bash
# Clone the repository
git clone git@gitlab.com:sck/emailsenderutils.git EmailSenderUtils
cd EmailSenderUtils

# Create a virtual environment and install all development dependencies
make venv
source venv/bin/activate
make init
make sync-devci
```

Run quality checks (format, lint, type check, test):

```bash
make qa
```

### Release cycle

1. Edit code and add change notes to the `Next Release (TBD)` entry in
   `HISTORY.md` as you go.

2. When ready to release, upgrade all dependencies and refresh the environment:

    ```bash
    make update
    make sync-devci
    ```

3. Run the full quality check suite:

    ```bash
    make qa
    ```

4. In `HISTORY.md`, replace the `Next Release (TBD)` heading with the release
   version and today's date, and verify the change notes are complete.

5. Sync the version to `pyproject.toml` and `uv.lock`:

    ```bash
    make set-version
    ```

6. Commit the release:

    ```bash
    git commit -am "Release X.Y.Z"
    ```

7. Tag and push.  `make tag` validates version consistency across `HISTORY.md`,
   `pyproject.toml`, and `uv.lock`; creates an annotated tag; pushes it to
   `origin`; and adds a new `Next Release (TBD)` entry to `HISTORY.md`:

    ```bash
    make tag
    ```

    Pushing the tag triggers the GitLab CI/CD publish job, which uploads
    the package to your selected registry.

8. Commit to open the next development cycle:

    ```bash
    git commit -am "Start next development cycle"
    ```

9. Go back to step 1.

See [Release Checklist](docs/release_checklist.md) for the full recurring workflow.

## License

MIT.

## Acknowledgements

Built with [Cookiecutter](https://github.com/cookiecutter/cookiecutter) and
the [sck/cookiecutter-pypackage-gitlab](https://gitlab.com/sck/cookiecutter-pypackage-gitlab)
project template.
