sygmail 0.1.2

Lightweight Gmail notification wrapper

sygmail

Lightweight wrapper for sending Gmail notifications with simple defaults and a .env config.

Features

• Load settings from .env and environment variables
• Save settings from code (persist=True)
• Defaults for subject/contents with {script_name} placeholder
• Optional auto-attachments from a path

Install

pip install sygmail

Requirements

• Python 3.9+
• Dependencies: yagmail, keyring

Quick start

from sygmail import Sygmail

syg = Sygmail()
syg.configure(
    from_addr="[e-mail]",
    app_password="app-password",
    persist=True,
)
syg.send()

.env keys

SYGMAIL_FROM=[e-mail]
SYGMAIL_APP_PASSWORD=app-password
SYGMAIL_TO=[e-mail]
SYGMAIL_SUBJECT=Process Completed
SYGMAIL_CONTENTS={script_name} has finished running.
SYGMAIL_ATTACHMENTS_PATH=/path/to/folder

If you use keyring, you can leave SYGMAIL_APP_PASSWORD empty.

Keyring usage:

python -m sygmail config set --from [e-mail] --app-password "app-password" --use-keyring
python -m sygmail send

Notes:

• Passwords are stored under the service name sygmail with the from address as the username.
• If SYGMAIL_APP_PASSWORD is set, it is used first; otherwise keyring is used.
• Storage uses your OS credential manager (macOS Keychain, Windows Credential Manager, or a Linux keyring).
• To remove a stored password, delete it from your OS credential manager.

Defaults

• Subject: Process Completed
• Contents: {script_name} has finished running.

Reset back to defaults:

syg.reset_subject_contents(persist=True)

Attachments behavior

• If attachments is provided in send(), it is used as-is.
• If attachments is not provided, and SYGMAIL_ATTACHMENTS_PATH is set, files under that path are attached (files only, no folders).

Examples:

syg.send(attachments=["./a/file.txt"])  # use only this
syg.send(attachments=[])               # explicitly no attachments
syg.send()                             # auto-attach from SYGMAIL_ATTACHMENTS_PATH if set

CLI

Use python -m sygmail for now:

python -m sygmail send

Options:

python -m sygmail send \
    --env .env \
    --from [e-mail] \
    --to [e-mail] \
    --subject "Process Completed" \
    --contents "[sygmail notification]" \
    --attachments /path/to/file \
    --attachments-path /path/to/folder/

• If --contents is omitted, CLI uses [sygmail notification] without editing .env.

Common examples:

python -m sygmail send

python -m sygmail send --subject "Job Done" --contents "[sygmail notification]"

python -m sygmail send --attachments /path/to/file-a.txt /path/to/file-b.txt

python -m sygmail send --attachments-path /path/to/folder/

python -m sygmail config set --from [e-mail] --app-password "app-password"

python -m sygmail config set --from [e-mail] --app-password "app-password" --use-keyring

python -m sygmail config show

Config commands:

python -m sygmail config set \
    --env .env \
    --from [e-mail] \
    --app-password "app-password" \
    --to [e-mail] \
    --subject "Process Completed" \
    --contents "{script_name} has finished running." \
    --attachments-path /path/to/folder/

python -m sygmail config reset --env .env

python -m sygmail config show --env .env

python -m sygmail config show --env .env --raw

API

Sygmail(env_path=".env")
Sygmail.configure(
    from_addr=None,
    from_=None,
    app_password=None,
    to=None,
    subject=None,
    contents=None,
    attachments_path=None,
    persist=True,
)
Sygmail.reset_subject_contents(persist=True)
Sygmail.send(
    from_addr=None,
    from_=None,
    to=None,
    subject=None,
    contents=None,
    attachments=None,
    attachments_path=None,
    **kwargs,
)

Notes

• Use a Gmail app password (not your normal password).
• Settings are stored in .env in the current working directory by default.
• If to is omitted, the message is sent to the same address as from_addr.

Security

• Do not commit .env to public repos.
• Treat app passwords like secrets.

Operations

• Prefer chmod 600 .env on shared machines.
• Use --env to separate configs per project.