# futuremail
Send emails like it's "the future". This email client has a Python user interface (no user interface) for maximum customizability in how you send and draft emails. Those who already know Python will find this much easier to use than both Mail Merge and Python's built-in emailing tools.
Install with `pip install futuremail`. See the source code here: [github.com/wheelercj/futuremail](https://github.com/wheelercj/futuremail). Be sure to avoid naming any of your Python files the same as one built into the Python language, such as `email.py`.
## features
* Write emails in a string with either markdown, plain text, or HTML. Markdown gets converted to HTML.
* Files are easy to attach and images are easy to embed.
* Quickly load contacts. Many file types and string formats are supported.
* Be confident. You can use `futuremail.assert_unique` to raise an exception if you accidentally reuse something between runs, and futuremail can often detect other common mistakes like forgetting to attach a file.
* Settings such as email server, email port, etc. are usually detected automatically.
* The code is easy to read and change. Type hints and docstrings are used almost everywhere possible, and the code has been auto-formatted with Black.
Here is a small example, and a more comprehensive one is at the end of this page.
```python
from futuremail import Sender, create_email_message, contacts # https://pypi.org/project/futuremail
import os
from textwrap import dedent
from dotenv import load_dotenv # https://pypi.org/project/python-dotenv/
load_dotenv()
contacts_str = dedent(
# first_name, last_name, email_address, group_name
"""\
Maximillian, Marsh, remedy@inbox.com, member
Kolby, Bradshaw, publisher@mail.com, member
Virginia, Andersen, suburb@gmail.com, member
Braiden, Villanueva, resolution@yahoo.com, member
""" # This contact info is fake.
)
my_email_address = os.environ.get("EMAIL_ADDRESS")
my_email_password = os.environ.get("EMAIL_PASSWORD")
subject = "This is the email's subject"
recipients = contacts.load_from_str(contacts_str)
with Sender(my_email_address, my_email_password) as sender:
for recipient in recipients:
email_content = dedent(
f"""\
Greetings {recipient.first_name},
This email was created and sent with Python!
"""
)
msg = create_email_message(
from_address=my_email_address,
subject=subject,
plaintext_content=email_content,
md_content=email_content,
to_addresses=[recipient.email_address],
)
sender.send(msg)
```
## public functions and classes
For each of the functions for loading contacts, a filter predicate can be provided to filter out some contacts. If a contacts file is used, the first row of the file is ignored by default. The order of the columns in the file must be the same as the order of the variables in the Contact class (you can just rearrange the Contact class if needed).
**futuremail.assert_unique** - Asserts that the given text has not been used before with the given key. Given strings are saved to a local sqlite3 database file named `unique_strings.db`. If the same two strings are given again, an exception is raised.
**futuremail.contacts.Contact** - A dataclass for holding one person's contact info.
**futuremail.contacts.Contacts** - A class for holding multiple Contact objects.
**futuremail.contacts.load_from_csv** - Loads contacts from a CSV file.
**futuremail.contacts.load_from_str** - Loads contacts from a string. By default, each contact must be on its own line and must contain the comma-separated data specified in the Contact class (in contacts.py). The delimiter is easy to change from a comma to anything else.
**futuremail.contacts.load_from_tsv** - Loads contacts from a TSV file.
**futuremail.contacts.load_from_xlsx** - Loads contacts from an XLSX file.
**futuremail.create_email_message** - Creates an email message object.
**futuremail.Drafter** - A context manager that creates an object for drafting emails using an email message object.
**futuremail.localhost_send** - Sends an email using an email object to localhost for testing.
**futuremail.log** - Logs the current time and the recipient(s) and subject of an email message object.
**futuremail.Sender** - A context manager that creates an object for sending emails using an email message object. By default, each email's send time, subject, and recipient(s) are logged to a file named `sent.log`.
## large example
```python
from futuremail import Sender, create_email_message, contacts, assert_unique
import os
from textwrap import dedent
from dotenv import load_dotenv # https://pypi.org/project/python-dotenv/
load_dotenv()
# The format of the contact info below is based on the Contact dataclass in
# contacts.py, which you can change at any time.
contacts_str = dedent(
# first_name, last_name, email_address, group_name
"""\
For, Testing, different.email@duck.com, me
Maximillian, Marsh, remedy@inbox.com, member
Kolby, Bradshaw, shout@outlook.com, member
Virginia, Andersen, suburb@gmail.com, member
Braiden, Villanueva, resolution@yahoo.com, member
Alissa, Douglas, achievement@gmail.com, member
Miracle, Buckley, someone@icloud.com, member
Taylor, Nelson, seminar@mail.com, member
Tamara, Snyder, reappoint@gmail.com, member
Haleigh, Rios, publisher@icloud.com, member
Charity, Parrish, language@yahoo.com, member
"""
# If you prefer, you could instead keep the contact info in an XLSX, CSV,
# or TSV file and load it with the appropriate futuremail load function in
# place of `contacts.load_from_str`.
)
my_email_address = os.environ.get("EMAIL_ADDRESS")
my_email_password = os.environ.get("EMAIL_PASSWORD")
subject = "This is the email's subject"
assert_unique(subject, "subject")
recipients = contacts.load_from_str(contacts_str, lambda x: x.group_name == "me")
attachment_paths = ["C:/Users/chris/Documents/book voucher.pdf"]
# I happen to use an absolute file path here and for an embedded image below,
# but you can just use the file's name if it's in the same folder as the source
# code.
for path in attachment_paths:
assert_unique(path, "attachment paths")
with Sender(my_email_address, my_email_password) as sender:
for recipient in recipients:
email_content = dedent(
f"""\
Greetings {recipient.first_name},
This is a sample email. These can be written in markdown (like this
one), HTML, or in plain text.
The first line of this email will show the correct first name for
each recipient, and it's easy to add more info that's different for
each person. Just add a variable to the Contact dataclass in
contacts.py and add to your list of contact info.
## markdown syntax samples
All of these markdown elements will be converted to HTML and will
look great in the final result, including:
* bullet points
* [links to websites](https://zombo.com/)
* embedded images (see below)
* **bold** and _italic_
* headers
* numbered list items
* tables
* and more
Everything in markdown works, which includes basically everything
commonly used in emails.
1. The numbers for these numbered
1. list items will be automatically
1. changed to the correct numbers.
Here's an embedded image:
I have also attached a file by adding its file path to the
attachment_paths list, as you can see above this email.
Let me know if you have any questions or concerns!
Kind regards,
Chris Wheeler
christopher.wheeler.320@my.csun.edu
"""
# If you use markdown and want multiple lines (that are not bullet
# points, ordered list items, etc.) next to each other like in the
# email signature, make sure you end each line with two (or more)
# spaces. Markdown removes the line breaks otherwise.
)
msg = create_email_message(
from_address=my_email_address,
subject=subject,
plaintext_content=email_content,
md_content=email_content,
attachment_paths=attachment_paths,
to_addresses=[recipient.email_address],
)
sender.send(msg)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/wheelercj/futuremail",
"name": "futuremail",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "email,smtp,futuremail",
"author": "Chris Wheeler",
"author_email": "christopher.wheeler.320@my.csun.edu",
"download_url": "https://files.pythonhosted.org/packages/78/b5/0fbabdc3e87c7a18abf6fc840d396f51388594e4f676b772ceca5467bdb4/futuremail-1.1.3.tar.gz",
"platform": "unix",
"description": "# futuremail\r\n\r\nSend emails like it's \"the future\". This email client has a Python user interface (no user interface) for maximum customizability in how you send and draft emails. Those who already know Python will find this much easier to use than both Mail Merge and Python's built-in emailing tools.\r\n\r\nInstall with `pip install futuremail`. See the source code here: [github.com/wheelercj/futuremail](https://github.com/wheelercj/futuremail). Be sure to avoid naming any of your Python files the same as one built into the Python language, such as `email.py`.\r\n\r\n## features\r\n\r\n* Write emails in a string with either markdown, plain text, or HTML. Markdown gets converted to HTML.\r\n* Files are easy to attach and images are easy to embed.\r\n* Quickly load contacts. Many file types and string formats are supported.\r\n* Be confident. You can use `futuremail.assert_unique` to raise an exception if you accidentally reuse something between runs, and futuremail can often detect other common mistakes like forgetting to attach a file.\r\n* Settings such as email server, email port, etc. are usually detected automatically.\r\n* The code is easy to read and change. Type hints and docstrings are used almost everywhere possible, and the code has been auto-formatted with Black.\r\n\r\nHere is a small example, and a more comprehensive one is at the end of this page.\r\n\r\n```python\r\nfrom futuremail import Sender, create_email_message, contacts # https://pypi.org/project/futuremail\r\nimport os\r\nfrom textwrap import dedent\r\nfrom dotenv import load_dotenv # https://pypi.org/project/python-dotenv/\r\nload_dotenv()\r\n\r\ncontacts_str = dedent(\r\n # first_name, last_name, email_address, group_name\r\n \"\"\"\\\r\n Maximillian, Marsh, remedy@inbox.com, member\r\n Kolby, Bradshaw, publisher@mail.com, member\r\n Virginia, Andersen, suburb@gmail.com, member\r\n Braiden, Villanueva, resolution@yahoo.com, member\r\n \"\"\" # This contact info is fake.\r\n)\r\n\r\nmy_email_address = os.environ.get(\"EMAIL_ADDRESS\")\r\nmy_email_password = os.environ.get(\"EMAIL_PASSWORD\")\r\nsubject = \"This is the email's subject\"\r\nrecipients = contacts.load_from_str(contacts_str)\r\n\r\nwith Sender(my_email_address, my_email_password) as sender:\r\n for recipient in recipients:\r\n email_content = dedent(\r\n f\"\"\"\\\r\n Greetings {recipient.first_name},\r\n\r\n This email was created and sent with Python!\r\n \"\"\"\r\n )\r\n\r\n msg = create_email_message(\r\n from_address=my_email_address,\r\n subject=subject,\r\n plaintext_content=email_content,\r\n md_content=email_content,\r\n to_addresses=[recipient.email_address],\r\n )\r\n\r\n sender.send(msg)\r\n```\r\n\r\n## public functions and classes\r\n\r\nFor each of the functions for loading contacts, a filter predicate can be provided to filter out some contacts. If a contacts file is used, the first row of the file is ignored by default. The order of the columns in the file must be the same as the order of the variables in the Contact class (you can just rearrange the Contact class if needed).\r\n\r\n**futuremail.assert_unique** - Asserts that the given text has not been used before with the given key. Given strings are saved to a local sqlite3 database file named `unique_strings.db`. If the same two strings are given again, an exception is raised.\r\n\r\n**futuremail.contacts.Contact** - A dataclass for holding one person's contact info.\r\n\r\n**futuremail.contacts.Contacts** - A class for holding multiple Contact objects.\r\n\r\n**futuremail.contacts.load_from_csv** - Loads contacts from a CSV file.\r\n\r\n**futuremail.contacts.load_from_str** - Loads contacts from a string. By default, each contact must be on its own line and must contain the comma-separated data specified in the Contact class (in contacts.py). The delimiter is easy to change from a comma to anything else.\r\n\r\n**futuremail.contacts.load_from_tsv** - Loads contacts from a TSV file.\r\n\r\n**futuremail.contacts.load_from_xlsx** - Loads contacts from an XLSX file.\r\n\r\n**futuremail.create_email_message** - Creates an email message object.\r\n\r\n**futuremail.Drafter** - A context manager that creates an object for drafting emails using an email message object.\r\n\r\n**futuremail.localhost_send** - Sends an email using an email object to localhost for testing.\r\n\r\n**futuremail.log** - Logs the current time and the recipient(s) and subject of an email message object.\r\n\r\n**futuremail.Sender** - A context manager that creates an object for sending emails using an email message object. By default, each email's send time, subject, and recipient(s) are logged to a file named `sent.log`.\r\n\r\n## large example\r\n\r\n```python\r\nfrom futuremail import Sender, create_email_message, contacts, assert_unique\r\nimport os\r\nfrom textwrap import dedent\r\nfrom dotenv import load_dotenv # https://pypi.org/project/python-dotenv/\r\nload_dotenv()\r\n\r\n# The format of the contact info below is based on the Contact dataclass in\r\n# contacts.py, which you can change at any time.\r\ncontacts_str = dedent(\r\n # first_name, last_name, email_address, group_name\r\n \"\"\"\\\r\n For, Testing, different.email@duck.com, me\r\n Maximillian, Marsh, remedy@inbox.com, member\r\n Kolby, Bradshaw, shout@outlook.com, member\r\n Virginia, Andersen, suburb@gmail.com, member\r\n Braiden, Villanueva, resolution@yahoo.com, member\r\n Alissa, Douglas, achievement@gmail.com, member\r\n Miracle, Buckley, someone@icloud.com, member\r\n Taylor, Nelson, seminar@mail.com, member\r\n Tamara, Snyder, reappoint@gmail.com, member\r\n Haleigh, Rios, publisher@icloud.com, member\r\n Charity, Parrish, language@yahoo.com, member\r\n \"\"\"\r\n # If you prefer, you could instead keep the contact info in an XLSX, CSV,\r\n # or TSV file and load it with the appropriate futuremail load function in\r\n # place of `contacts.load_from_str`.\r\n)\r\n\r\nmy_email_address = os.environ.get(\"EMAIL_ADDRESS\")\r\nmy_email_password = os.environ.get(\"EMAIL_PASSWORD\")\r\nsubject = \"This is the email's subject\"\r\nassert_unique(subject, \"subject\")\r\nrecipients = contacts.load_from_str(contacts_str, lambda x: x.group_name == \"me\")\r\nattachment_paths = [\"C:/Users/chris/Documents/book voucher.pdf\"]\r\n# I happen to use an absolute file path here and for an embedded image below,\r\n# but you can just use the file's name if it's in the same folder as the source\r\n# code.\r\nfor path in attachment_paths:\r\n assert_unique(path, \"attachment paths\")\r\n\r\nwith Sender(my_email_address, my_email_password) as sender:\r\n for recipient in recipients:\r\n email_content = dedent(\r\n f\"\"\"\\\r\n Greetings {recipient.first_name},\r\n\r\n This is a sample email. These can be written in markdown (like this\r\n one), HTML, or in plain text.\r\n \r\n The first line of this email will show the correct first name for\r\n each recipient, and it's easy to add more info that's different for\r\n each person. Just add a variable to the Contact dataclass in\r\n contacts.py and add to your list of contact info.\r\n\r\n ## markdown syntax samples\r\n\r\n All of these markdown elements will be converted to HTML and will\r\n look great in the final result, including:\r\n \r\n * bullet points\r\n * [links to websites](https://zombo.com/)\r\n * embedded images (see below)\r\n * **bold** and _italic_\r\n * headers\r\n * numbered list items\r\n * tables\r\n * and more\r\n \r\n Everything in markdown works, which includes basically everything\r\n commonly used in emails.\r\n\r\n 1. The numbers for these numbered\r\n 1. list items will be automatically\r\n 1. changed to the correct numbers.\r\n\r\n Here's an embedded image:\r\n\r\n \r\n\r\n I have also attached a file by adding its file path to the\r\n attachment_paths list, as you can see above this email.\r\n\r\n Let me know if you have any questions or concerns!\r\n\r\n Kind regards, \r\n Chris Wheeler \r\n christopher.wheeler.320@my.csun.edu \r\n \"\"\"\r\n # If you use markdown and want multiple lines (that are not bullet\r\n # points, ordered list items, etc.) next to each other like in the\r\n # email signature, make sure you end each line with two (or more)\r\n # spaces. Markdown removes the line breaks otherwise.\r\n )\r\n\r\n msg = create_email_message(\r\n from_address=my_email_address,\r\n subject=subject,\r\n plaintext_content=email_content,\r\n md_content=email_content,\r\n attachment_paths=attachment_paths,\r\n to_addresses=[recipient.email_address],\r\n )\r\n\r\n sender.send(msg)\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Send emails with Python",
"version": "1.1.3",
"split_keywords": [
"email",
"smtp",
"futuremail"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c5a15363c1408e181b6b15e798133004304446b6e40c5c30242b0127d6591112",
"md5": "8dced826a4a47d0f9b265bd8fc8f41cb",
"sha256": "da93c1166d4665b09ead2daa5bb4bb2cb5948f7ac9e148e928d5647b48d44944"
},
"downloads": -1,
"filename": "futuremail-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8dced826a4a47d0f9b265bd8fc8f41cb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20986,
"upload_time": "2023-01-18T05:12:00",
"upload_time_iso_8601": "2023-01-18T05:12:00.301322Z",
"url": "https://files.pythonhosted.org/packages/c5/a1/5363c1408e181b6b15e798133004304446b6e40c5c30242b0127d6591112/futuremail-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "78b50fbabdc3e87c7a18abf6fc840d396f51388594e4f676b772ceca5467bdb4",
"md5": "3836dbb33b44f31bcccd744c5a0bde78",
"sha256": "7fae8a5137d0587f1c8b276bed37d60fa906b1b1444a533d9166ec7e2fc4aa37"
},
"downloads": -1,
"filename": "futuremail-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "3836dbb33b44f31bcccd744c5a0bde78",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14208,
"upload_time": "2023-01-18T05:12:01",
"upload_time_iso_8601": "2023-01-18T05:12:01.760187Z",
"url": "https://files.pythonhosted.org/packages/78/b5/0fbabdc3e87c7a18abf6fc840d396f51388594e4f676b772ceca5467bdb4/futuremail-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-18 05:12:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "wheelercj",
"github_project": "futuremail",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "futuremail"
}
JSON
