# MailToolsBox
MailToolsBox is a Python package that provides two classes to help you
interact with emails: SendAgent and ImapAgent.
# Installation
Use the package manager PyPI <https://pypi.org/project/MailToolsBox/> to
install MailToolsBox.
You can install MailToolsBox via pip:
```bash
pip install MailToolsBox
```
SendAgent Class (Send SMTP Usage) \-\-\-\-\-\-\-\-\-\-\-\-\-\--The
SendAgent class allows you to send emails through SMTP. Here is an
example of how to use this class:
```pycon
from MailToolsBox import SendAgent
user_email = "example@gmail.com"
user_email_password = "password"
server_smtp_address = "smtp.gmail.com"
port = 587
send_agent = SendAgent(user_email, server_smtp_address, user_email_password, port)
recipient_email = "example@example.com"
subject = "Test email"
message_body = "This is a test email sent from MailToolsBox."
send_agent.send_mail(recipient_email, subject, message_body)
```
# send_mail method
The send_mail method sends an email to one or more recipients and optionally includes attachments.
Parameters:
recipient_email: the email address of the recipient. Can be a string or a list of strings for multiple recipients.
subject: the subject of the email.
message_body: the body of the email.
cc (optional): a list of email addresses to be included in the CC field.
bcc (optional): a list of email addresses to be included in the BCC field.
attachments (optional): a list of file paths to be attached to the email.
tls (optional, default True): enable Transport Layer Security.
server_quit (optional, default False): whether to quit the SMTP server after sending the email.
# ImapAgent Class
The ImapAgent class provides functionality for connecting to an email
server via the Internet Message Access Protocol (IMAP) and downloading
emails from the server.
# IMAP CLIENT Usage
To use the ImapAgent class, you first need to create an instance of the
class and provide your email account information and the address of the
email server that you want to connect to:
```pycon
from MailToolsBox import ImapAgent
email_account = 'your_email@example.com'
password = 'your_email_password'
server_address = 'imap.example.com'
imap_agent = ImapAgent(email_account, password, server_address)
imap_agent.download_mail_text() # optional parameter : (lookup='ALL',save=True,path='/home/user/')
imap_agent.download_mail_json() # return json format | optional parameter : (lookup='ALL',save=True,filename='filename.json',path='/home/user/')
imap_agent.download_mail_msg() # optional parameter : (lookup='ALL',path='/home/user/')
```
# Methods
login_account(): This method connects to the email server and logs in to
your email account using your email address and password.
download_mail_text(): This method downloads the text content of all the
emails in the specified mailbox and saves the content to a text file.
The method takes the following parameters:
path (optional): The path where you want to save the text file. If not
specified, the text file will be saved in the current working directory.
mailbox (optional): The name of the mailbox that you want to download
emails from. If not specified, the emails in the INBOX mailbox will be
downloaded.
# Attachment, CC, and BCC
MailToolsBox provides additional features such as the ability to send email attachments, specify CC and BCC recipients, in addition to the recipient_email parameter.
# Attachments
To include attachments in your email, you can pass a list of file paths to the attachments parameter in the send_mail() method. MailToolsBox will read the attachment files and add them as MIMEApplication objects to your email message.
# CC and BCC
To specify CC and BCC recipients, you can pass a list of email addresses to the cc and bcc parameters in the send_mail() method. The addresses will be added to the email message headers.
Here is an example of how to use the cc and bcc parameters:
```pycon
from MailToolsBox import SendAgent
user_email = "example@gmail.com"
user_email_password = "password"
server_smtp_address = "smtp.gmail.com"
port = 587
send_agent = SendAgent(user_email, server_smtp_address, user_email_password, port)
recipient_email = "example@example.com"
cc = ["example2@example.com", "example3@example.com"]
bcc = ["example4@example.com"]
subject = "Test email"
message_body = "This is a test email sent from MailToolsBox."
attachments = ["path/to/file1.pdf", "path/to/file2.txt"]
send_agent.send_mail(recipient_email, subject, message_body, cc=cc, bcc=bcc, attachments=attachments)
```
In this example, the email is sent to recipient_email, with CC recipients example2@example.com and example3@example.com, and BCC recipient example4@example.com. The email also contains two attachments: file1.pdf and file2.txt.
# Conclusion
MailToolsBox provides a simple and easy-to-use interface for sending and receiving emails. With the SendAgent and ImapAgent classes, you can easily integrate email functionality into your Python applications.
# Contributing
Pull requests are welcome. For major changes, please open an issue first
to discuss what you would like to change.
Please make sure to update tests as appropriate.
# License
MIT \| <https://choosealicense.com/licenses/mit/>
Raw data
{
"_id": null,
"home_page": "https://www.rambod.net",
"name": "MailToolsBox",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Mail,Server,smtp,send,email,tools,box",
"author": "Rambod Ghashghai",
"author_email": "gh.rambod@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1b/4c/3d36fe861694603bf971713a22cd7b4c3281884442ffedfb0406d154e3da/MailToolsBox-0.1.0.4.tar.gz",
"platform": null,
"description": "# MailToolsBox\r\n\r\nMailToolsBox is a Python package that provides two classes to help you\r\ninteract with emails: SendAgent and ImapAgent.\r\n\r\n# Installation\r\n\r\nUse the package manager PyPI <https://pypi.org/project/MailToolsBox/> to\r\ninstall MailToolsBox.\r\n\r\nYou can install MailToolsBox via pip:\r\n\r\n```bash\r\npip install MailToolsBox\r\n```\r\n\r\nSendAgent Class (Send SMTP Usage) \\-\\-\\-\\-\\-\\-\\-\\-\\-\\-\\-\\-\\-\\--The\r\nSendAgent class allows you to send emails through SMTP. Here is an\r\nexample of how to use this class:\r\n\r\n```pycon\r\nfrom MailToolsBox import SendAgent\r\n\r\nuser_email = \"example@gmail.com\"\r\nuser_email_password = \"password\"\r\nserver_smtp_address = \"smtp.gmail.com\"\r\nport = 587\r\n\r\nsend_agent = SendAgent(user_email, server_smtp_address, user_email_password, port)\r\nrecipient_email = \"example@example.com\"\r\nsubject = \"Test email\"\r\nmessage_body = \"This is a test email sent from MailToolsBox.\"\r\nsend_agent.send_mail(recipient_email, subject, message_body)\r\n```\r\n\r\n# send_mail method\r\n\r\nThe send_mail method sends an email to one or more recipients and optionally includes attachments.\r\n\r\nParameters:\r\nrecipient_email: the email address of the recipient. Can be a string or a list of strings for multiple recipients.\r\nsubject: the subject of the email.\r\nmessage_body: the body of the email.\r\ncc (optional): a list of email addresses to be included in the CC field.\r\nbcc (optional): a list of email addresses to be included in the BCC field.\r\nattachments (optional): a list of file paths to be attached to the email.\r\ntls (optional, default True): enable Transport Layer Security.\r\nserver_quit (optional, default False): whether to quit the SMTP server after sending the email.\r\n\r\n# ImapAgent Class\r\n\r\nThe ImapAgent class provides functionality for connecting to an email\r\nserver via the Internet Message Access Protocol (IMAP) and downloading\r\nemails from the server.\r\n\r\n# IMAP CLIENT Usage\r\n\r\nTo use the ImapAgent class, you first need to create an instance of the\r\nclass and provide your email account information and the address of the\r\nemail server that you want to connect to:\r\n\r\n```pycon\r\nfrom MailToolsBox import ImapAgent\r\n\r\nemail_account = 'your_email@example.com'\r\npassword = 'your_email_password'\r\nserver_address = 'imap.example.com'\r\n\r\nimap_agent = ImapAgent(email_account, password, server_address)\r\nimap_agent.download_mail_text() # optional parameter : (lookup='ALL',save=True,path='/home/user/')\r\nimap_agent.download_mail_json() # return json format | optional parameter : (lookup='ALL',save=True,filename='filename.json',path='/home/user/')\r\nimap_agent.download_mail_msg() # optional parameter : (lookup='ALL',path='/home/user/')\r\n\r\n```\r\n\r\n# Methods\r\n\r\nlogin_account(): This method connects to the email server and logs in to\r\nyour email account using your email address and password.\r\n\r\ndownload_mail_text(): This method downloads the text content of all the\r\nemails in the specified mailbox and saves the content to a text file.\r\nThe method takes the following parameters:\r\n\r\npath (optional): The path where you want to save the text file. If not\r\nspecified, the text file will be saved in the current working directory.\r\n\r\nmailbox (optional): The name of the mailbox that you want to download\r\nemails from. If not specified, the emails in the INBOX mailbox will be\r\ndownloaded.\r\n\r\n# Attachment, CC, and BCC\r\n\r\nMailToolsBox provides additional features such as the ability to send email attachments, specify CC and BCC recipients, in addition to the recipient_email parameter.\r\n\r\n# Attachments\r\n\r\nTo include attachments in your email, you can pass a list of file paths to the attachments parameter in the send_mail() method. MailToolsBox will read the attachment files and add them as MIMEApplication objects to your email message.\r\n\r\n# CC and BCC\r\n\r\nTo specify CC and BCC recipients, you can pass a list of email addresses to the cc and bcc parameters in the send_mail() method. The addresses will be added to the email message headers.\r\n\r\nHere is an example of how to use the cc and bcc parameters:\r\n\r\n```pycon\r\nfrom MailToolsBox import SendAgent\r\n\r\nuser_email = \"example@gmail.com\"\r\nuser_email_password = \"password\"\r\nserver_smtp_address = \"smtp.gmail.com\"\r\nport = 587\r\n\r\nsend_agent = SendAgent(user_email, server_smtp_address, user_email_password, port)\r\nrecipient_email = \"example@example.com\"\r\ncc = [\"example2@example.com\", \"example3@example.com\"]\r\nbcc = [\"example4@example.com\"]\r\nsubject = \"Test email\"\r\nmessage_body = \"This is a test email sent from MailToolsBox.\"\r\nattachments = [\"path/to/file1.pdf\", \"path/to/file2.txt\"]\r\nsend_agent.send_mail(recipient_email, subject, message_body, cc=cc, bcc=bcc, attachments=attachments)\r\n\r\n```\r\n\r\nIn this example, the email is sent to recipient_email, with CC recipients example2@example.com and example3@example.com, and BCC recipient example4@example.com. The email also contains two attachments: file1.pdf and file2.txt.\r\n\r\n# Conclusion\r\n\r\nMailToolsBox provides a simple and easy-to-use interface for sending and receiving emails. With the SendAgent and ImapAgent classes, you can easily integrate email functionality into your Python applications.\r\n\r\n# Contributing\r\n\r\nPull requests are welcome. For major changes, please open an issue first\r\nto discuss what you would like to change.\r\n\r\nPlease make sure to update tests as appropriate.\r\n\r\n# License\r\n\r\nMIT \\| <https://choosealicense.com/licenses/mit/>\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Mail tools simplify mail server and sender development for developers.",
"version": "0.1.0.4",
"split_keywords": [
"mail",
"server",
"smtp",
"send",
"email",
"tools",
"box"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1b4c3d36fe861694603bf971713a22cd7b4c3281884442ffedfb0406d154e3da",
"md5": "2e2d221889317150788676baca7fa387",
"sha256": "aa407239e9a2d626361babdcf7f1b0904250dd5ab4b38e9079e51d306f0b2375"
},
"downloads": -1,
"filename": "MailToolsBox-0.1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "2e2d221889317150788676baca7fa387",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6669,
"upload_time": "2023-04-18T12:08:51",
"upload_time_iso_8601": "2023-04-18T12:08:51.324605Z",
"url": "https://files.pythonhosted.org/packages/1b/4c/3d36fe861694603bf971713a22cd7b4c3281884442ffedfb0406d154e3da/MailToolsBox-0.1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-18 12:08:51",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "mailtoolsbox"
}
JSON