A Python library for simplified email sending and receiving with secure credentials management
Project description
MailScript
A Python library for simplified email sending and receiving with support for templates, attachments, and more.
Features
- Send plain text and HTML emails
- Template rendering with Jinja2
- Email address validation
- File attachments
- Support for CC and BCC recipients
- TLS/SSL encryption
- Receive emails via IMAP
- Extract and save email attachments
- Output emails in JSON format
Installation
pip install mailscript
Configuration
MailScript provides multiple ways to configure your email credentials:
Option 1: Direct Configuration
Provide credentials directly to the Mailer or Receiver classes:
from mailscript import Mailer
mailer = Mailer(
smtp_host="smtp.example.com",
smtp_port=587,
smtp_user="your-email@example.com",
smtp_password="your-password",
use_tls=True
)
Option 2: Configuration File
Create a configuration file in one of these locations:
./config/mailscript_config.py~/.config/mailscript/config.py./mailscript_config.py
Example configuration file:
# mailscript_config.py
smtp_config = {
"username": "your-email@example.com",
"password": "your-password",
"host": "smtp.example.com",
"port": 587,
"use_tls": True
}
imap_config = {
"username": "your-email@example.com",
"password": "your-password",
"host": "imap.example.com",
"port": 993
}
default_recipient = "recipient@example.com"
Then use the credential loader:
from mailscript import Mailer
from mailscript.credentials import get_smtp_config
smtp_config = get_smtp_config()
mailer = Mailer(
smtp_host=smtp_config["host"],
smtp_port=smtp_config["port"],
smtp_user=smtp_config["username"],
smtp_password=smtp_config["password"],
use_tls=smtp_config["use_tls"]
)
Quick Start
Basic Usage
from mailscript import Mailer
# Initialize mailer
mailer = Mailer(
smtp_host="smtp.example.com",
smtp_port=587,
smtp_user="your-email@example.com",
smtp_password="your-password",
use_tls=True
)
# Send a simple email
mailer.send(
sender="your-email@example.com",
recipients="recipient@example.com",
subject="Hello from MailScript",
body="This is a test email from MailScript."
)
HTML Emails
# Send an HTML email
html_content = """
<!DOCTYPE html>
<html>
<body>
<h1>Hello from MailScript</h1>
<p>This is an <b>HTML</b> email!</p>
</body>
</html>
"""
mailer.send(
sender="your-email@example.com",
recipients="recipient@example.com",
subject="HTML Email Test",
body=html_content,
is_html=True
)
Template Rendering
from mailscript.templates import TemplateRenderer
# Initialize renderer
renderer = TemplateRenderer()
# Render template from string
template = """
<h1>Hello, {{ name }}!</h1>
<p>Welcome to {{ company }}.</p>
"""
context = {"name": "John", "company": "Example Corp"}
html_content = renderer.render_from_string(template, context)
# Send templated email
mailer.send(
sender="your-email@example.com",
recipients="recipient@example.com",
subject="Welcome Email",
body=html_content,
is_html=True
)
Built-in Template Methods
# Send an email using a template string directly
context = {
"name": "John",
"features": ["Templates", "Attachments", "HTML Support"]
}
mailer.send_template(
sender="your-email@example.com",
recipients="recipient@example.com",
subject="Welcome Email",
template_string="<h1>Welcome, {{ name }}!</h1><ul>{% for feature in features %}<li>{{ feature }}</li>{% endfor %}</ul>",
context=context,
is_html=True
)
# Send an email using a template file
mailer.send_template_file(
sender="your-email@example.com",
recipients="recipient@example.com",
subject="Newsletter",
template_name="newsletter.html",
template_folder="/path/to/templates",
context={"name": "John", "month": "June"},
is_html=True
)
With Attachments
# Send email with attachment
with open("document.pdf", "rb") as f:
attachments = {"document.pdf": f}
mailer.send(
sender="your-email@example.com",
recipients="recipient@example.com",
subject="Email with attachment",
body="Please find the attached document.",
attachments=attachments
)
Receiving Emails
from mailscript import Receiver
# Initialize receiver
receiver = Receiver(
imap_host="imap.example.com",
imap_port=993,
username="your-email@example.com",
password="your-password"
)
# Connect to the server
receiver.connect()
# Select mailbox
receiver.select_mailbox("INBOX")
# Fetch recent emails
emails = receiver.fetch_emails(
count=5, # Number of recent emails to retrieve
save_attachments=True, # Save attachments to disk
output_dir="./my_attachments" # Directory to save attachments
)
# Process emails
for email in emails:
print(f"From: {email['from']}")
print(f"Subject: {email['subject']}")
print(f"Date: {email['date']}")
print(f"Body: {email['body'][:100]}...") # Print first 100 chars
# Process attachments
for attachment in email['attachments']:
print(f"Attachment: {attachment['filename']}")
print(f"Saved at: {attachment['saved_path']}")
print("---")
# Always logout when done
receiver.logout()
Command Line Usage
Sending Emails
# Send a plain text email
python -m mailscript send --host smtp.example.com --port 587 --user user@example.com \
--from "Sender <sender@example.com>" --to recipient@example.com \
--subject "Hello" --body "This is a test email"
# Send an HTML email with attachments
python -m mailscript send --host smtp.example.com --port 587 --user user@example.com \
--from "Sender <sender@example.com>" --to recipient@example.com \
--subject "Hello" --body-file email.html --html --attach document.pdf image.jpg
Receiving Emails
# Retrieve 10 recent emails and display them
python -m mailscript receive --host imap.example.com --port 993 --user user@example.com \
--count 10
# Retrieve emails and save attachments
python -m mailscript receive --host imap.example.com --port 993 --user user@example.com \
--count 5 --save-attachments --output-dir ./downloads
# Save email data to a JSON file
python -m mailscript receive --host imap.example.com --port 993 --user user@example.com \
--output-file emails.json
Development
Version Management
This project uses a central version.txt file to manage versioning. When updating the version:
- Edit the version number in
version.txt - Run the update script to propagate the version to all relevant files:
python update_version.py
This script automatically updates:
mailscript/__init__.py- Updates the__version__variabledocs/index.md- Updates the "Current Version" text in the documentation
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT License
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
mailscript-0.2.1.tar.gz
(24.7 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file mailscript-0.2.1.tar.gz.
File metadata
- Download URL: mailscript-0.2.1.tar.gz
- Upload date:
- Size: 24.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
28db6ec8651cda86cae2761a80f49f448c358ad2d5ac770ca60623118a079f45
|
|
| MD5 |
2ca74efb255c2543cd7f5a54b73748dc
|
|
| BLAKE2b-256 |
aa01389fe0c4a2f8aa0fe27326c2409c8f8991e84899f14f89860784c1bf24f4
|
File details
Details for the file mailscript-0.2.1-py2.py3-none-any.whl.
File metadata
- Download URL: mailscript-0.2.1-py2.py3-none-any.whl
- Upload date:
- Size: 15.9 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e90995dae72c3c978227fb374ee2e188293ab95ff09110dfbb1b789c99064652
|
|
| MD5 |
b87cdcd6ea6e14fd99dcc48ae565dfea
|
|
| BLAKE2b-256 |
862e0a5971c9240ec6dca48b2bbefc42a9b934695adcd8da51f9e04fbf807c68
|
