Package: emailee
emaileeA robust SMTP mailer library, with async mail send features built-in using Threads and Multiprocessing. Zero PyPI (production) dependencies.InstallationInstall withpip install emailee.Some quick examplesSend a simple text emailimportemaileemy_email=emailee.Emailee()my_email.sender("john.smith@fakeemail.com")my_email.subject("Test email")my_email.msgContent("some poorly formatted raw text")my_email.sendTo(["jill.smith@fakeemail.com"])my_email.server("smtp.fakeemail.com")ifmy_email.ready():my_email.send()Send multiple asyncronous emailsimportemaileeemails_list=[{...}]server_dict={...}emails=emailee.AsyncThreads(emails_list,server_dict,outputFile='output.txt')DocumentationThere are only three classes exposed to the user of this library,Emailee,AsyncThreadsandAsyncMP. The latter two utilise the Emailee class to send emails via the Threading or Multiprocessing async APIs respectively.Emailee classIf you have used thesmtplibandemaillibraries in the past, you may of found how difficult it is getting the email logic set up properly to handle attachments and different sending scenarios. All customisations are built into Emailee, which takes the guess work out of how to configure.The following methods are exposed to the user:Emailee.sender(sender: str, replyTo: str = "") -> Nonesender- email address of who is sending the emailreplyTo(optional) - alternative email address the receiver can reply toEmailee.subject(subject: str = "") -> Nonesubject(optional) - email subject line, maximum of 255 charactersEmailee.msgContent(msgText: str = "", msgHTML: str = "") -> NonemsgText(optional) - email message in raw text formatmsgHTML(optional) - email message in email HTML formatIt's a good idea to use both of these to replicate your email, so users who can't read HTML emails can read your fallback raw text email. Look online for HTML email generatorsEmailee.sendTo(to: List[str] = [], cc: List[str] = [], bcc: List[str] = [], ignoreErrors: bool = False) -> Noneto(optional) - list of to addresses to send emails tocc(optional) - list of cc addresses to send emails tobcc(optional) - list of bcc addresses to send emails toignoreErrors(optional) - all addresses are validated by regex to be in a valid email format. By default, if an email address is found to be invalid the program will raise an exception. If changed to True, the program will ignore and remove invalid emails and continue with sending the email.Emailee.attachmentFiles(attachmentFiles: List[str] = []) -> NoneattachmentFiles(optional) - list of attachments for email, can be listed by relative or full pathEmailee.server(smtpServer: str, port: int = 0, SSLTLS: str = "", authUsername: str = "", authPassword: str = "", timeout: int = 30) -> NonesmtpServer- server name or IP address of SMTP serverport(optional) - port number for SMTP server, if connection not authenticated and port left blank, port will default to 25. If connection set to SSL or TLS and port left blank, port will default to 465 or 587 respectively.SSLTLS(optional) - encrypted connection setting, value either "SSL" or "TLS"authUsername(optional) - username for logging into the SMTP server, if authentication required. If left blank, but authPassword filled in, this will default to the sender email.authPassword(optional) - password for logging into the SMTP servertimeout(optional) - server connection and email send timeout limit. Extend this value if on a slow network, or sending emails with large attachmentsEmailee.ready() -> boolReturns True if the minimal fields to send an email have been set.Email.send(outputFile: str) -> booloutputFile(optional) - relative or full path location of a file to write report output metadata to, required for async classes when sending mail, file must be empty or not currently existReturns True if successful, does not guarantee email was delivered, just sent.Email.repr() -> strPrint class function, will print a dictionary of email metadata, useful for testing and debugging.Data for async classesBoth async classes are very similar in their function and both require emails and server config in the exact same format:mail_list=[{'sender':sender# see Emailee.sender()'replyTo':replyTo# see Emailee.sender()'subject':email_subject# see Emailee.subject()'msgText':raw_text_message# see Emailee.msgContent()'msgHTML':HTML_formatted_message# see Emailee.msgContent()'to':list_of_to_emails# see Emailee.sendTo()'cc':list_of_cc_emails# see Emailee.sendTo()'bcc':list_of_bcc_emails# see Emailee.sendTo()'ignoreErrors':True# see Emailee.sendTo()'attachmentFiles':list_of_attachment_file_paths# see Emailee.attachmentFiles()},{...},]server_dict={'smtpServer':SMTP_server# see Emailee.server()'port':port_number# see Emailee.server()'SSLTLS':'TLS'# see Emailee.server()'authUsername':authenticated_username# see Emailee.server()'authPassword':authenticated_password# see Emailee.server()}AsyncThreads classAsyncThreads uses the threading API to enable asyncronous sending of email. Threading only utilises the same CPU core that the Python program is currently running on, so it can only maximise a single core usage, but the benefits are you can throttle how many threads are allowed to run concurrently and it has a lower overhead compared toAsyncMP.AsyncThreads(mailList: List[Dict], serverDict: Dict, outputFile: str, maxThreads: int = 10, waitTime: float = 0)mailList- see mail_list above for formatserverDict- see server_dict above for formatoutputFile- relative or full path location of a file to write report output metadata to, file must be empty or not currently exist. Mandatory for async classes to handle errors.maxThreads- maximum number of concurrent threads to send emails onwaitTime- wait time in seconds to pause between each thread being spawned, this helps if your SMTP server throttles your connection if you send too many emails in a short time spanAsyncMP classAsyncMP uses the multiprocessing API to enable asyncronous sending of email. Multiprocessing utilises all CPU cores of the system the Python program is running on, but does not allow throttling, so you run the risk of maxing out your CPU and RAM, slowing down your system.AsyncMP(mailList: List[Dict], serverDict: Dict, outputFile: str, waitTime: float = 0)mailList- see mail_list above for formatserverDict- see server_dict above for formatoutputFile- relative or full path location of a file to write report output metadata to, file must be empty or not currently exist. Mandatory for async classes to handle errors.waitTime- wait time in seconds to pause between each process being spawned, this helps if your SMTP server throttles your connection if you send too many emails in a short time spanReporting on async outputUpon completion of either async class, you can call theemailReport()method to return a metadata list of all emails sent.
This won't work if an exception is thrown during the sending process, hence theoutputFilerequirement.
The output file will be written to after each successful email send so you can analyse againstemailReport()or see who received emails before a thrown exception or manual cancellation of the sending process.Development and TestingEmailee is built withpoetry, tested withpytest,toxandcoverage, type checked withmypyand formatted withblack.Dev InstallationInstall with PoetryClone the repo,cdinto it and runpoetry installInstall with pipClone the repo,cdinto it, build and run a new virtual environment, then open thepyproject.tomlfile andpip installall packages listed under[tool.poetry.dev-dependencies]TestingTo successfully run local tests you will need to renametests/example.test.env.tomltotests/test.env.tomland modify the config inside the file to contain valid email and SMTP server connection data.Testing and coverage can then be run withpytest --cov-report term-missing --cov=emailee testsTox can be used to run pytest against all support Python environments. Opentox.iniand check if you have all versions of Python installed listed underenvlist.Pre-commit hooksRunpre-commit installto install the pre-commit hooks in the.pre-commit-config.yamlfile. Then runpre-commit run --all-filesto auto-check every file for issues.Feel free to send me any changes or feedback.Thanks for reading :):envelope: :envelope: :envelope: :envelope: :envelope: