micromail/README.md

# micromail

[![Forgejo Actions](https://code.edgarpierre.fr/edpibu/micromail/badges/workflows/release.yaml/badge.svg?&label=release&style=for-the-badge)](https://code.edgarpierre.fr/edpibu/micromail/actions?workflow=release.yaml)
[![Release](https://code.edgarpierre.fr/edpibu/micromail/badges/release.svg?logo=micropython&label=&style=for-the-badge)](https://code.edgarpierre.fr/edpibu/micromail/releases/latest)

![](./logo.svg)

Tiny SMTP client for Micropython. See [examples](examples) for usage.

Inspired from [shawwwn/uMail](https://github.com/shawwwn/uMail).

## Installation

### Manual
Copy the `micromail.py` file to your device. You will need to install the `datetime` library as well.

### MIP
```python
>>> import mip
>>> mip.install("https://code.edgarpierre.fr/edpibu/micromail/releases/download/latest/")
```

## Documentation

### Class MicromailClient

- `class micromail.MicromailClient(host: str, port: int = 0, ssl: bool = False, starttls: bool = False)`

    Create a new SMTP client.

- `MicromailClient.connect()`


    Establish a connection to the SMTP server. The connection is kept alive until `MicromailClient.quit()` is called.

- `MicromailClient.login(username: str, password: str)`

    Login to the SMTP server with the provided username and password. `PLAIN` and `LOGIN` authentication methods are currently supported.

- `MicromailClient.write(data: str | bytes)`

    Write `data` of type `bytearray` on the server.

- `MicromailClient.send_command(*cmd: str | bytes, code: int | list[int] = []) -> tuple[int, list[str]]`

    Send command to the SMTP server; returns status code and list of response lines.

- `MicromailClient.read_res(cmd: str = "", code: int | list[int] = []) -> tuple[int, list[str]]`

    Read response from the SMTP server; returns status code and list of response lines.

- `MicromailClient.ehlo() -> list[str]`

    Send SMTP EHLO command to the server and return response.

- `MicromailClient.starttls()`

    Send SMTP STARTTLS command and enable SSL on socket.

- `MicromailClient.new_message(to: str | list[str], sender: str | None = None)`

    Create a new email; sender defaults to username.

- `MicromailClient.headers(headers: dict[str, str])`

    Define email headers; supported headers are `date` (`str`, defaults to current date), `from` (defaults to `new_message` `sender`), `to` (defaults to `new_message` `to`), `subject` (`str`).

- `MicromailClient.write_line(content: str)`

    Write message line; `\r\n` is appended to `content`.

- `MicromailClient.send()`

    Send current email.

- `MicromailClient.quit()`

    Quit the SMTP server and disconnect from socket.

### Functions

- `format_date(date: datetime) -> str`

    Return date formatted as email date string.

### Exceptions

- `Error`

    Standard module error.

- `NoSocketError`

    Raised when an operation on the socket is asked but the client is not connected to any socket.

- `SMTPError(cmd: str, code: int, message: str)`

    Raised when an unexpected SMTP response code is received.