ultrasmtp 1.0.0

UltraSMTP is a lightweight Python library for sending emails with attachments and HTML templates. It provides easy configuration for common SMTP settings and offers template-based email rendering.

UltraSMTP

UltraSMTP is a lightweight Python library for sending emails with attachments and HTML templates. It provides easy configuration for common SMTP settings and offers template-based email rendering.

Features

• Simple configuration of SMTP details (host, port, username, password).
• Support for plain and HTML email content.
• Built-in template loading with customizable placeholders.
• Flexible handling of recipients (To, CC, BCC) and display names.
• Attach multiple files effortlessly.
• Preview text insertion for better email client previews.

Installation

To install UltraSMTP, you can use pip:

pip install ultrasmtp

Usage

1. Import and initialize the UltraSMTP class with your SMTP credentials:

   from ultrasmtp import UltraSMTP
   
   email = UltraSMTP("smtp_host", 587, "username", "password")
   

2. Use the send_email method to send emails:

   email.send_email(
       to="[e-mail]",
       subject="Hello from UltraSMTP!",
       body="This is an email body.",
       html_template="default",
       attachments=["/path/to/file1.pdf", "/path/to/file2.png"]
   )
   

Functions

UltraSMTP.init(smtp_host, smtp_port, username, password)

• Initializes the UltraSMTP object.
• Parameters:
  • smtp_host (str): SMTP server address.
  • smtp_port (int): SMTP port (commonly 587).
  • username (str): Login username.
  • password (str): Login password.

UltraSMTP.send_email(...)

• Sends an email.
• Parameters:
  • to (str | list | dict | list[dict]): Recipient or multiple recipients; supports name/email dicts.
  • subject (str): Email subject.
  • body (str): Main email content (plain text or HTML).
  • from_email (str): Sender's email address (defaults to username).
  • from_name (str): Sender's display name.
  • reply_to (str | dict): Reply-to address.
  • cc (str | list | dict | list[dict]): CC recipients.
  • bcc (str | list | dict | list[dict]): BCC recipients.
  • preview_text (str): Hidden snippet for email preview.
  • attachments (list[str]): File paths to attach.
  • html_template (str): Template name without file extension.
  • template_path (str): Custom HTML template path.

Example

from ultrasmtp import UltraSMTP

creds = {
   "smtp_server": "smtp.example.com",
   "smtp_port": 587,
   "sender_email": "[e-mail]",
   "sender_password": "examplepass"
}

email = UltraSMTP(
   creds["smtp_server"],
   creds["smtp_port"],
   creds["sender_email"],
   creds["sender_password"]
)

email.send_email(
   to=["[e-mail]", {"email": "[e-mail]", "name": "Bob"}],
   subject="Greetings!",
   body="<p>This is an <b>HTML</b> email</p>",
   from_name="Your Name",
   preview_text="Short preview goes here",
   attachments=["/path/to/report.pdf"]
)

Detailed Parameters

to

• Type: str | list | dict | list[dict]
• Description: Recipient or multiple recipients. Supports name/email dictionaries.
• Examples:
  • "[e-mail]"
  • ["[e-mail]", "[e-mail]"]
  • {"email": "[e-mail]", "name": "Recipient Name"}
  • [{"email": "[e-mail]", "name": "Recipient One"}, {"email": "[e-mail]", "name": "Recipient Two"}]

subject

• Type: str
• Description: The subject of the email.

body

• Type: str
• Description: The main content of the email. Can be plain text or HTML.

from_email

• Type: str
• Description: The sender's email address. Defaults to the username provided during initialization.

from_name

• Type: str
• Description: The display name of the sender.

reply_to

• Type: str | dict
• Description: The reply-to address. Can be a string or a dictionary with 'email' and 'name'.

cc

• Type: str | list | dict | list[dict]
• Description: CC recipients. Supports multiple formats similar to to.

bcc

• Type: str | list | dict | list[dict]
• Description: BCC recipients. Supports multiple formats similar to to.

preview_text

• Type: str
• Description: A hidden snippet for email preview in clients.

attachments

• Type: list[str]
• Description: List of file paths to attach to the email.

html_template

• Type: str
• Description: The name of the HTML template to use (without file extension).

template_path

• Type: str
• Description: Custom path to an HTML template file.

Enhanced Documentation

UltraSMTP is designed to be simple yet powerful. It supports both plain text and HTML emails with customizable templates and attachments. This guide provides a step-by-step approach, detailed API reference, and practical examples.

Quick Start

1. Install UltraSMTP:

pip install ultrasmtp

2. Initialize the library:

from ultrasmtp import UltraSMTP

creds = {
   "smtp_server": "smtp.example.com",
   "smtp_port": 587,
   "sender_email": "[e-mail]",
   "sender_password": "examplepass",
   "from_email": "[e-mail]",
   "reply_to": "[e-mail]"
}

email = UltraSMTP(creds)

3. Send an email:

email.send_email(
   to="[e-mail]",
   from_name="Your Name",
   subject="Hello from UltraSMTP!",
   plain_content="This is an email body.",
   html_template_path="path/to/template.html",
   attachments=["/path/to/file.pdf"]
)

Advanced Usage

• Multiple recipients and CC/BCC support:

email.send_email(
   to=["[e-mail]", {"email": "[e-mail]", "name": "Bob"}],
   cc="[e-mail]",
   bcc="[e-mail]",
   subject="Group Email",
   plain_content="This email contains multiple recipients."
)

• Custom HTML templates with placeholders:

email.send_email(
   to="[e-mail]",
   from_name="Your Company",
   subject="Welcome!",
   plain_content="Welcome to our service.",
   html_template_path="templates/welcome.html",
   placeholders={"{{username}}": "User"}
)

Examples Folder

For a comprehensive demonstration, refer to the examples in the examples folder.