picoware.applications.email

module documentation

Email - Send and receive email via SMTP and IMAP.

Class	`IMAP4`	A minimal IMAP4 client for MicroPython.
Class	`IMAPAsync`	Threaded IMAP helper so network fetches don't block the UI.
Class	`SMTP`	A minimal SMTP client for MicroPython.
Class	`SMTPAsync`	Threaded version of SMTP for sending emails "asynchronously"
Function	`imap_fetch_email_by_uid`	Fetch a single email by IMAP UID.
Function	`imap_fetch_unread_emails`	Fetch summaries of the most recent unread emails.
Function	`imap_mark_seen`	Mark an email as seen by IMAP UID.
Function	`run`	Run the app.
Function	`start`	Start the app.
Function	`stop`	Stop the app.
Constant	`AUTH_LOGIN`	Undocumented
Constant	`AUTH_PLAIN`	Undocumented
Constant	`CMD_AUTH`	Undocumented
Constant	`CMD_EHLO`	Undocumented
Constant	`CMD_MAIL`	Undocumented
Constant	`CMD_STARTTLS`	Undocumented
Constant	`DEFAULT_TIMEOUT`	Undocumented
Constant	`EMAIL_LIST_FETCHING`	Undocumented
Constant	`EMAIL_LIST_READY`	Undocumented
Constant	`EMAIL_VIEW_FETCHING`	Undocumented
Constant	`EMAIL_VIEW_READY`	Undocumented
Constant	`IMAP_DEFAULT_TIMEOUT`	Undocumented
Constant	`KEYBOARD_ENTERING`	Undocumented
Constant	`KEYBOARD_WAITING`	Undocumented
Constant	`LOCAL_DOMAIN`	Undocumented
Constant	`MAX_BODY_LENGTH`	Undocumented
Constant	`MENU_ITEM_READ_EMAILS`	Undocumented
Constant	`MENU_ITEM_SEND_MESSAGE`	Undocumented
Constant	`MENU_ITEM_SET_EMAIL`	Undocumented
Constant	`MENU_ITEM_SET_NAME`	Undocumented
Constant	`MENU_ITEM_SET_PASSWORD`	Undocumented
Constant	`SENDING_KEYBOARD`	Undocumented
Constant	`SENDING_SENDING`	Undocumented
Constant	`SENDING_WAITING`	Undocumented
Constant	`VIEW_EMAIL_LIST`	Undocumented
Constant	`VIEW_EMAIL_VIEW`	Undocumented
Constant	`VIEW_KEYBOARD_EMAIL`	Undocumented
Constant	`VIEW_KEYBOARD_NAME`	Undocumented
Constant	`VIEW_KEYBOARD_PASSWORD`	Undocumented
Constant	`VIEW_KEYBOARD_RECIPIENT`	Undocumented
Constant	`VIEW_KEYBOARD_SUBJECT`	Undocumented
Constant	`VIEW_MAIN_MENU`	Undocumented
Constant	`VIEW_SENDING_MESSAGE`	Undocumented
Variable	`email_subject`	Undocumented
Variable	`recipient_email`	Undocumented
Variable	`sender_app_password`	Undocumented
Variable	`sender_email`	Undocumented
Variable	`sender_name`	Undocumented
Variable	`smtp`	Undocumented
Function	`__await_send`	Wait for email sending to complete.
Function	`__load_email_credentials`	Load email credentials from storage.
Function	`_b64decode`	Decode base64 bytes, tolerating whitespace and missing padding.
Function	`_back_to_email_list`	Return from viewing an email to the email list.
Function	`_build_email_list`	Build the List widget from the fetched unread emails.
Function	`_decode_body_part`	Decode a MIME body part into a unicode string.
Function	`_decode_encoded_words`	Decode RFC 2047 encoded-words in a header value.
Function	`_email_list_run`	Run the email list view.
Function	`_email_view_run`	Run the single-email view.
Function	`_extract_email_address`	Extract the email address from a From/To header value.
Function	`_extract_plain_text`	Extract the plain-text body from a raw MIME body + headers dict.
Function	`_first_header`	Get the first value for a header name.
Function	`_header_param`	Get a parameter value from a header value.
Function	`_keyboard_run`	Start the keyboard view.
Function	`_keyboard_save`	Keyboard callback to save the entered value.
Function	`_loading_run`	Start the loading view.
Function	`_mark_seen_and_refresh`	Mark the current email as seen, then refresh the unread list.
Function	`_menu_start`	Start the menu view.
Function	`_open_email`	Open a single email: fetch its body and show it.
Function	`_parse_headers`	Parse a raw header block into a dict of name -> [values].
Function	`_q_decode`	Decode an RFC 2047 Q-encoded string into unicode.
Function	`_qp_decode_bytes`	Decode a quoted-printable byte string.
Function	`_reset_email_list`	Clear the email list state.
Function	`_show_email`	Render a fetched email in a scrollable text box.
Function	`_split_message`	Split an RFC822 message into (header_blob, body_blob).
Function	`_walk_multipart`	Walk a multipart body and return concatenated text/plain parts.
Variable	`_current_email`	Undocumented
Variable	`_email_list`	Undocumented
Variable	`_email_textbox`	Undocumented
Variable	`_imap`	Undocumented
Variable	`_loading`	Undocumented
Variable	`_menu`	Undocumented
Variable	`_message_to_send`	Undocumented
Variable	`_unread_emails`	Undocumented

def imap_fetch_email_by_uid(from_email, from_pass, uid, mark_seen=False): ¶

Fetch a single email by IMAP UID.

Parameters
from_email:`str`	The sender email.
from_pass:`str`	The sender app password.
uid:`str`	The message UID.
mark_seen:`bool`	Mark the email as seen. Defaults to False.

Returns
`dict or None`	The email details.

Raises
`OSError`	On connection errors.

def imap_fetch_unread_emails(from_email, from_pass, limit=10): ¶

Fetch summaries of the most recent unread emails.

Parameters
from_email:`str`	The sender email.
from_pass:`str`	The sender app password.
limit:`int`	Maximum number of emails. Defaults to 10.

Returns
`list`	uid/subject/from/to/date dicts (newest first).

Raises
`OSError`	On connection or auth errors.

def imap_mark_seen(from_email, from_pass, uid): ¶

Mark an email as seen by IMAP UID.

Parameters
from_email:`str`	The sender email.
from_pass:`str`	The sender app password.
uid:`str`	The message UID.

Returns
`bool`	True on success.

def run(view_manager): ¶

Run the app.

Parameters
view_manager:`ViewManager`	The view manager context.

@storage_required
@wifi_required

def start(view_manager) -> bool: ¶

Start the app.

Parameters
view_manager:`ViewManager`	The view manager context.

Returns
`bool`	True on success.

def stop(view_manager): ¶

Stop the app.

Parameters
view_manager:`ViewManager`	The view manager context.

AUTH_LOGIN: str = ¶

Undocumented

Value

'LOGIN'

AUTH_PLAIN: str = ¶

Undocumented

Value

'PLAIN'

CMD_AUTH: str = ¶

Undocumented

Value

'AUTH'

CMD_EHLO: str = ¶

Undocumented

Value

'EHLO'

CMD_MAIL: str = ¶

Undocumented

Value

'MAIL'

CMD_STARTTLS: str = ¶

Undocumented

Value

'STARTTLS'

DEFAULT_TIMEOUT = ¶

Undocumented

Value

const(10)

EMAIL_LIST_FETCHING = ¶

Undocumented

Value

const(0)

EMAIL_LIST_READY = ¶

Undocumented

Value

const(1)

EMAIL_VIEW_FETCHING = ¶

Undocumented

Value

const(0)

EMAIL_VIEW_READY = ¶

Undocumented

Value

const(1)

IMAP_DEFAULT_TIMEOUT = ¶

Undocumented

Value

const(30)

KEYBOARD_ENTERING = ¶

Undocumented

Value

const(0)

KEYBOARD_WAITING = ¶

Undocumented

Value

const((-1))

LOCAL_DOMAIN: str = ¶

Undocumented

Value

'127.0.0.1'

MAX_BODY_LENGTH = ¶

Undocumented

Value

const((48 * 1024))

MENU_ITEM_READ_EMAILS = ¶

Undocumented

Value

const(1)

MENU_ITEM_SEND_MESSAGE = ¶

Undocumented

Value

const(0)

MENU_ITEM_SET_EMAIL = ¶

Undocumented

Value

const(2)

MENU_ITEM_SET_NAME = ¶

Undocumented

Value

const(4)

MENU_ITEM_SET_PASSWORD = ¶

Undocumented

Value

const(3)

SENDING_KEYBOARD = ¶

Undocumented

Value

const(0)

SENDING_SENDING = ¶

Undocumented

Value

const(1)

SENDING_WAITING = ¶

Undocumented

Value

const((-1))

VIEW_EMAIL_LIST = ¶

Undocumented

Value

const(7)

VIEW_EMAIL_VIEW = ¶

Undocumented

Value

const(8)

VIEW_KEYBOARD_EMAIL = ¶

Undocumented

Value

const(3)

VIEW_KEYBOARD_NAME = ¶

Undocumented

Value

const(5)

VIEW_KEYBOARD_PASSWORD = ¶

Undocumented

Value

const(4)

VIEW_KEYBOARD_RECIPIENT = ¶

Undocumented

Value

const(2)

VIEW_KEYBOARD_SUBJECT = ¶

Undocumented

Value

const(6)

VIEW_MAIN_MENU = ¶

Undocumented

Value

const(0)

VIEW_SENDING_MESSAGE = ¶

Undocumented

Value

const(1)

email_subject: str = ¶

Undocumented

recipient_email: str = ¶

Undocumented

sender_app_password: str = ¶

Undocumented

sender_email: str = ¶

Undocumented

sender_name: str = ¶

Undocumented

smtp = ¶

Undocumented

def __await_send(view_manager): ¶

Wait for email sending to complete.

Parameters
view_manager:`ViewManager`	The view manager context.

def __load_email_credentials(view_manager) -> bool: ¶

Load email credentials from storage.

Parameters
view_manager:`ViewManager`	The view manager context.

Returns
`bool`	True if credentials are set.

def _b64decode(data): ¶

Decode base64 bytes, tolerating whitespace and missing padding.

Parameters
data:`bytes or str`	The base64 data.

Returns
`bytes`	The decoded bytes.

def _back_to_email_list(view_manager): ¶

Return from viewing an email to the email list.

Parameters
view_manager:`ViewManager`	The view manager context.

def _build_email_list(view_manager): ¶

Build the List widget from the fetched unread emails.

Parameters
view_manager:`ViewManager`	The view manager context.

def _decode_body_part(data, cte, charset=None): ¶

Decode a MIME body part into a unicode string.

Parameters
data:`bytes`	The body part data.
cte:`str`	The content transfer encoding.
charset:`str`	The character set. Defaults to None.

Returns
`str`	The decoded text.

def _decode_encoded_words(raw): ¶

Decode RFC 2047 encoded-words in a header value.

Parameters
raw:`str`	The header value.

Returns
`str`	The decoded value.

def _email_list_run(view_manager) -> bool: ¶

Run the email list view.

Parameters
view_manager:`ViewManager`	The view manager context.

Returns
`bool`	False when leaving the view.

def _email_view_run(view_manager) -> bool: ¶

Run the single-email view.

Parameters
view_manager:`ViewManager`	The view manager context.

Returns
`bool`	False when leaving the view.

def _extract_email_address(header): ¶

Extract the email address from a From/To header value.

Parameters
header:`str`	The header value.

Returns
`str`	The email address.

def _extract_plain_text(body_blob, headers): ¶

Extract the plain-text body from a raw MIME body + headers dict.

Parameters
body_blob:`bytes`	The message body.
headers:`dict`	Parsed headers.

Returns
`str`	The plain-text body.

def _first_header(headers, name): ¶

Get the first value for a header name.

Parameters
headers:`dict`	Parsed headers.
name:`str`	The header name.

Returns
`str`	The first value, or "".

def _header_param(header_value, param): ¶

Get a parameter value from a header value.

Parameters
header_value:`str`	The header value.
param:`str`	The parameter name.

Returns
`str or None`	The parameter value.

def _keyboard_run(view_manager) -> bool: ¶

Start the keyboard view.

Parameters
view_manager:`ViewManager`	The view manager context.

Returns
`bool`	True while the keyboard is active.

def _keyboard_save(view_manager) -> bool: ¶

Keyboard callback to save the entered value.

Parameters
view_manager:`ViewManager`	The view manager context.

Returns
`bool`	True on success.

def _loading_run(view_manager, message: str = 'Sending...'): ¶

Start the loading view.

Parameters
view_manager:`ViewManager`	The view manager context.
message:`str`	The loading message. Defaults to "Sending...".

def _mark_seen_and_refresh(view_manager): ¶

Mark the current email as seen, then refresh the unread list.

Parameters
view_manager:`ViewManager`	The view manager context.

def _menu_start(view_manager): ¶

Start the menu view.

Parameters
view_manager:`ViewManager`	The view manager context.

def _open_email(view_manager, summary): ¶

Open a single email: fetch its body and show it.

Parameters
view_manager:`ViewManager`	The view manager context.
summary:`dict`	The email summary.

def _parse_headers(header_blob): ¶

Parse a raw header block into a dict of name -> [values].

Parameters
header_blob:`bytes or str`	The raw header block.

Returns
`dict`	Header names mapped to value lists.

def _q_decode(s): ¶

Decode an RFC 2047 Q-encoded string into unicode.

Parameters
s:`str`	The Q-encoded string.

Returns
`str`	The decoded string.

def _qp_decode_bytes(data): ¶

Decode a quoted-printable byte string.

Parameters
data:`bytes`	The quoted-printable data.

Returns
`bytes`	The decoded bytes.

def _reset_email_list(): ¶

Clear the email list state.

def _show_email(view_manager, data): ¶

Render a fetched email in a scrollable text box.

Parameters
view_manager:`ViewManager`	The view manager context.
data:`dict`	The email details.

def _split_message(literal): ¶

Split an RFC822 message into (header_blob, body_blob).

Parameters
literal:`bytes`	The raw message.

Returns
`tuple`	(header_blob, body_blob).

def _walk_multipart(body_blob, boundary): ¶

Walk a multipart body and return concatenated text/plain parts.

Parameters
body_blob:`bytes`	The multipart body.
boundary:`str`	The MIME boundary.

Returns
`str`	The concatenated plain-text parts.

_current_email = ¶

Undocumented

_email_list = ¶

Undocumented

_email_textbox = ¶

Undocumented

_imap = ¶

Undocumented

_loading = ¶

Undocumented

_menu = ¶

Undocumented

_message_to_send: str = ¶

Undocumented

_unread_emails: list = ¶

Undocumented