NOTICE: All information contained herein is, and remains
the property of TechnoCore Automate.
ObjWebMail is a Python class for sending and receiving emails. It supports SMTP for sending and POP3 for receiving. It also has features for handling HTML emails, attachments, and processing multipart messages.
uuid(self, *args: Any) -> str:Generates a short, unique identifier.
Example:
webmail = WebMail()
unique_id = webmail.uuid()
print(unique_id)
__init__(self, database_connection: DatabaseConnection = 0):Initializes the WebMail object.
database_connection: An optional database connection object.Initializes _Executor for asynchronous email sending and pop3_port for POP3 server port configuration.
set_remote_connection(self, remote_connection: str = "") -> None:Sets the remote connection details for sending and receiving email. It first attempts to retrieve configuration from config.yaml using ConfigIni.Get. If the configuration for the specified remote_connection is found in config.yaml, those values are used. Otherwise, it falls back to querying the database for connection details.
remote_connection: The name of the remote connection to use. Defaults to "WEBMASTER".Example:
webmail = WebMail()
webmail.set_remote_connection("MY_EMAIL_CONFIG")
set_channel(self, channel: str = "") -> None:Sets the email channel and retrieves the corresponding remote connection.
channel: The name of the channel to use.Example:
webmail = WebMail()
webmail.set_channel("TRANSACTIONAL_EMAIL")
send(self, from_address: str, to_address: str, message: MIMEMultipart) -> str:Sends an email message using the configured SMTP server. This method now operates asynchronously by submitting the email sending task to a thread pool, preventing the main application thread from blocking. It also includes verbose debug logging to trace the entire SMTP communication process.
from_address: The sender's email address.to_address: The recipient's email address.message: A MIMEMultipart object representing the email to be sent.Example:
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
webmail = WebMail()
webmail.set_remote_connection("WEBMASTER")
msg = MIMEMultipart()
msg['Subject'] = 'Test Email'
msg['From'] = 'sender@example.com'
msg['To'] = 'recipient@example.com'
msg.attach(MIMEText('This is a test email.'))
status = webmail.send('sender@example.com', 'recipient@example.com', msg)
print(status)
attach_file(self, path: str, filename: str, force_main: str = "") -> MIMEBase:Attaches a file to an email message.
path: The full path to the file to attach.filename: The name of the file as it should appear in the email.force_main: Optionally force the main content type (e.g., "image").MIMEBase object representing the attachment.Example:
webmail = WebMail()
attachment = webmail.attach_file('/path/to/file.txt', 'document.txt')
send_text(self, from_address: str, to_address: str, subject: str, message: str, guid: str = "") -> None:Sends a plain text email asynchronously. The email sending task is submitted to a thread pool. This method also includes verbose debug logging to trace the parameters passed and the email content.
from_address: The sender's email address.to_address: The recipient's email address.subject: The subject of the email.message: The plain text message body.guid: An optional unique identifier for the email.Example:
webmail = WebMail()
webmail.set_remote_connection("WEBMASTER")
webmail.send_text(
'sender@example.com',
'recipient@example.com',
'Hello',
'This is a plain text email.'
)
envelope(self, html_content: str) -> str:Wraps HTML content in a basic HTML structure.
html_content: The HTML content to wrap.Example:
webmail = WebMail()
html = webmail.envelope('<p>This is a paragraph.</p>')
print(html)
send_html(self, from_address: str, to_address: str, subject: str, message: str, binary_files: List[Tuple[str, str]] = [], guid: str = "") -> str:Sends an HTML email with optional attachments.
from_address: The sender's email address.to_address: The recipient's email address.subject: The subject of the email.message: The HTML message body.binary_files: A list of tuples, where each tuple contains the folder and filename of an attachment.guid: An optional unique identifier for the email.Example:
webmail = WebMail()
webmail.set_remote_connection("WEBMASTER")
status = webmail.send_html(
'sender@example.com',
'recipient@example.com',
'HTML Email',
'<h1>Hello</h1><p>This is an HTML email.</p>',
binary_files=[('/path/to', 'image.jpg')]
)
print(status)
send_image(self, from_address: str, to_address: str, subject: str, image_file: str) -> None:Sends an email with an embedded image.
from_address: The sender's email address.to_address: The recipient's email address.subject: The subject of the email.image_file: The path to the image file.Example:
webmail = WebMail()
webmail.set_remote_connection("WEBMASTER")
webmail.send_image(
'sender@example.com',
'recipient@example.com',
'Image Email',
'/path/to/image.jpg'
)
send_file(self, from_address: str, to_address: str, subject: str, data_dir: str = "", data_file: str = "", message: str = "") -> None:Sends an email with a file attachment.
from_address: The sender's email address.to_address: The recipient's email address.subject: The subject of the email.data_dir: The directory where the file is located.data_file: The name of the file to attach.message: An optional message body.Example:
webmail = WebMail()
webmail.set_remote_connection("WEBMASTER")
webmail.send_file(
'sender@example.com',
'recipient@example.com',
'File Attachment',
data_dir='/path/to',
data_file='document.pdf',
message='Please find the attached document.'
)
process_mail(self, message: MIMEMultipart, message_number: int) -> None:Processes a single email message, extracting attachments and content.
message: The MIMEMultipart object to process.message_number: The message number in the mailbox.scan_mail(self) -> str:Scans a POP3 mailbox for new messages and processes them.
Example:
webmail = WebMail()
webmail.set_remote_connection("WEBMASTER")
webmail.scan_mail()
send_report(self, to_address, subject, html_body, ..., inline_images=[]) -> str:The canonical method for sending HTML emails.
Parameters:
to_address: Recipient(s), comma or semicolon separated.subject: Email subject line.html_body: HTML string for the body.from_address: Sender override (default: _Senderaddress).attachments: List of file paths to attach as downloads.guid: Optional Message-ID header.inline_images: List of file paths to embed as CID inline images.Returns: "DONE" on success, "FAIL" on error.
Uses Quoted-Printable encoding for HTML and sends per-recipient for clean To: headers.
Gmail and Outlook strip data: URI images from HTML
emails. The correct way to embed images is CID
(Content-ID) inline attachments.
Content-Disposition: inlineContent-ID header (e.g. <logo.png>)src="cid:logo.png"Pass image file paths to send_report(inline_images=...):
from ObjWebMail import WebMail
mailer = WebMail()
mailer.set_remote_connection("WEBMASTER")
html = '''
<h1>Report</h1>
<img src="cid:logo.jpg" style="max-height:48px" />
<p>See attached chart:</p>
<img src="cid:chart.png" />
'''
result = mailer.send_report(
"user@example.com",
"Monthly Report",
html,
inline_images=[
"/path/to/logo.jpg",
"/path/to/chart.png",
],
)
The Content-ID is set to the filename (e.g.
<logo.jpg>), so use cid:<filename> in the HTML.
ObjTemplate.build_email_html() handles CID
automatically. It returns (html, inline_images):
from ObjTemplate import ObjTemplate
from ObjWebMail import WebMail
tpl = ObjTemplate()
body = tpl.summary_box("Pipeline complete.")
body += tpl.section(
"Results",
["Metric", "Value"],
tpl.kv_row("Rows", "50"),
)
html, inline_images = tpl.build_email_html(
title="Report Title",
body_html=body,
subtitle="package | context",
)
mailer = WebMail()
mailer.set_remote_connection("WEBMASTER")
mailer.send_report(
"user@example.com",
"Report Title",
html,
inline_images=inline_images,
)
This embeds:
def_package.DefaultLogo)def_package.AgentLogo,technocore_logo.png)Both logos are auto-cropped to remove whitespace padding
via Pillow before embedding.
| Column | Table | Purpose | Default |
|---|---|---|---|
DefaultLogo |
def_package |
Client logo (header) | None |
AgentLogo |
def_package |
Platform logo (footer) | technocore_logo.png |
Logo files are resolved from:
resource.images/package.<pkg>/<filename>resource.images/package.base/<filename> (agent only)resource.web/<path>| Parameter | Content-Disposition | Use case |
|---|---|---|
attachments |
attachment |
Downloadable files (PDF, XLSX) |
inline_images |
inline |
Images displayed in the email body |
Both are MIME parts in the same email. The difference
is the disposition header — inline tells the email
client to render the image where the CID reference
appears in the HTML.
ObjWebMail can also be used as a command-line tool via typer. To run a command, use:
python3 ObjWebMail.py <command> [arguments]
show-credentials <remote_connection: str>Displays the email credentials for a given remote connection.
remote_connection: The name of the remote connection (e.g., "WEBMASTER").Example:
python3 ObjWebMail.py show-credentials WEBMASTER
send-test-email [to_address: str] [subject: str] [message: str] [--remote-connection: str]Sends a test email to a specified recipient.
to_address: The recipient email address. Defaults to vheyn@rimco.co.za.subject: The subject of the email. Defaults to "Test Email from ObjWebMail".message: The body of the email. Defaults to "This is a test email sent from ObjWebMail CLI.".--remote-connection: The remote connection to use for sending the email. Defaults to "WEBMASTER".Example:
python3 ObjWebMail.py send-test-email test@example.com "CLI Test" "This is a test from the CLI." --remote-connection MY_CONFIG