diff --git a/README.md b/README.md index 9f86bcb..c9903f9 100755 --- a/README.md +++ b/README.md @@ -1,48 +1,49 @@ -# µMail (MicroMail) -A lightweight, scalable SMTP client for sending email in MicroPython. - - -## Usage: - -A bare minimal approach - -```py -import umail -smtp = umail.SMTP('smtp.gmail.com', 587, username='my@gmail.com', password='mypassword') -smtp.to('someones@gmail.com') -smtp.send("This is an example.") -smtp.quit() -``` - - -## API docs: - -* **`umail.SMTP(host, port, [ssl, username, password])`** - * **host** - smtp server - * **port** - server's port number - * **ssl** - set `True` when SSL is required by the server - * **username** - my username/email to the server - * **password** - my password - -* **`SMTP.login(username, password)`** - If you did not login when intializing the server, do it here! - -* **`SMTP.to(addrs)`** - * **addrs** - Recipient's email address. If multiple recipents, use a list, eg. `['aaa@mail.com', 'bbb@mail.com']` - -* **`SMTP.write(content)`** - To send a long email or an email that contains large attachments, you will most likely exceed the memory limit of your MCU.\ - Use this function to break up your email into smaller chunks.\ - Each call to `write()` will cause the current `content` to be sent to the server so you can load the next chunk. - -* **`SMTP.send([content])`** - Finish writing the email.\ - Make the SMTP server to actually send your email to the recipent address. - -* **`SMTP.quit()`** - Close the connection to the server - - -## Other - -For more details, pleasse refer to sample code under `examples\` +# µMail (MicroMail) +A lightweight, scalable SMTP client for sending email in MicroPython. + + +## Usage: + +A bare minimal approach + +```py +import umail +smtp = umail.SMTP('smtp.gmail.com', 587, username='my@gmail.com', password='mypassword') +smtp.to('someones@gmail.com') +smtp.send("This is an example.") +smtp.quit() +``` + + +## API docs: + +* **`umail.SMTP(host, port, [ssl, username, password])`** + * **host** - smtp server + * **port** - server's port number + * **ssl** - set `True` when SSL is required by the server + * **username** - my username/email to the server + * **password** - my password + +* **`SMTP.login(username, password)`** + If you did not login when intializing the server, do it here! + +* **`SMTP.to(addrs, mail_from)`** + * **addrs** - Recipient's email address. If multiple recipents, use a list, eg. `['aaa@mail.com', 'bbb@mail.com']` + * **mail_from** - manually specify the MAIL FROM address, default value is your smtp username. [example](examples/example_mail_from.py) + +* **`SMTP.write(content)`** + To send a long email or an email that contains large attachments, you will most likely exceed the memory limit of your MCU.\ + Use this function to break up your email into smaller chunks.\ + Each call to `write()` will cause the current `content` to be sent to the server so you can load the next chunk. + +* **`SMTP.send([content])`** + Finish writing the email.\ + Make the SMTP server to actually send your email to the recipent address. + +* **`SMTP.quit()`** + Close the connection to the server + + +## Other + +For more details, pleasse refer to sample code under `examples\` diff --git a/examples/example_mail_from.py b/examples/example_mail_from.py new file mode 100755 index 0000000..04fdbd9 --- /dev/null +++ b/examples/example_mail_from.py @@ -0,0 +1,17 @@ +# +# Setting the MAIL FROM address +# +# Some services may require you to set the MAIL FROM address different than your +# login username. In such cases, you can manually specify the address by +# smtp.to(mail_from=address) +# If argument not set, MAIL FROM address will be default to your login username. +# +# Read more about MAIL FROM: +# https://docs.aws.amazon.com/ses/latest/DeveloperGuide/mail-from.html +# + +import umail +smtp = umail.SMTP('email-smtp.us-west-2.amazonaws.com', 587, username='myusername', password='mypassword') +smtp.to('someones@gmail.com', mail_from='my@gmail.com') +smtp.send("This is an example.") +smtp.quit()