wholemail 0.1.7

A lucid Python package built to facilitate easy sending of emails and other common generic functionality like sending authentication code emails

Introduction

• Wholemail is a lucid Python package built to facilitate easy sending of emails and other common generic functionality like sending authentication code emails .
• Jinja2 is used to render the HTML code , so that means you can add your own Jinja2 expressions and blocks like in the example below :

from wholemail import LoadTemplate , GmailWorker

worker = GmailWorker("[e-mail]" , "gmail_app_password") # will send the email
html_text = """
	
	{%if won_the_prize %}

		<h3>{{name}} , you won ! we'll contact you</h3>

	{%else%}
		<p>Better luck next time</p>
	{%endif%}

"""
context = {
	
	"name":"JaneDoe",
	"won_the_prize":True,
}

template = LoadTemplate(html_text = html_text , context = context )


recipient  ,subject = "[e-mail]" , "The prize"
# send the template 
worker.SendTemplate( template , subject ,recipient)

An example of preset email templates for you to choose from

Office letter template	Verificaton code template

---

Main features

• Easily send text-based and HTML emails
• Jinja2 expressions and blocks in your HTML code will be automatically rendered and processed
• Preset email templates lighten your load when you need to send for common generic emails . eg OTP email
• Create , customize and send your own email templates
• Saves you the hustle of writing email sending functions

• Check out the release notes to stay updated on recent changes and contributions
• More HTML templates needed , you are welcome to contribute a new HTML template
• Contributions and ideas are welcome , and for Pete's sake , help me write better code .
• More templates on the way
• Here are screenshots of all the preset templates for you to choose from

TAKE NOTE :

Before using with gmail

• If you want to send emails via gmail, make sure you set up your Gmail APP PASSWORD , otherwise using your NORMAL Gmail password WILL NOT work since Google disabled less secure apps
• Read more about GMAIL less secure apps

After setting up your password you can use it like so

from wholemail import GmailSender , GmailEmailWorker

gmail_address = "[e-mail]"
gmail_app_password = "123app"

# making GmailSender object
sender = GmailSender(  gmail_address , gmail_app_password )


# making a GmailWorker object
worker = GmailEmailWorker(gmail_address, gmail_app_password )

---

Getting started

Installation

Windows OS installation using pip

python3 -m pip install wholemail

alternatively

pip install wholemail

or

py -m pip install wholemail

To upgrade your version in Windows ,just use the --upgrade option when installing . Like so :

python -m pip install --upgrade wholemail

Dependencies

• Jinja2
• code-monger
• smptlib - Comes with the Python Standard Library
• bs4 - Beautiful soup

Supported emails

• Support for more email providers is on the way

• Gmail

• Yahoo

• Proton mail

• Outlook

Usage

Contents

• Sending emails via GMAIL
• Using the LoadTemplate function
• Working with the EmailTemplate class
• Working with the EmailWorker class
• Sending a generic email verification email
• Sending a generic authentication code email
• Using the EmailWorker to authenticate codes
• Using in a Django view
• Adding Javascript and CSS code to the HTML of an EmailTemplate class
• Changing preset email styles

---

Sending emails via GMAIL

• You can send html and plain text messages using the EmailSender class
• Here is a demonstration

from wholemail import GmailSender

# to send a gmail email you can use the GmailSender class
sender = GmailSender(  "[e-mail]" , "password" )

# To send a simple text based message , use the SendTextMail method like so
recipient = "[e-mail]" # recipients email address
message = "Hey there pal" # message to send
subject = "saying hello" # email subject

sender.SendTextMail( recipient , subject , message )# This will send an email to the recipient with the provided message


# to send a html message
html_code = "<h1>Hello  there pal</h1>" # html to send
subject = "saying hi" #  Subject of the email
plain_message = "Hello there" # alternative message to the html , it is optional

sender.SendHTMLEmail( recipient , subject ,html_code , plain_message = plain_message )
# This will send an html email to the recipient

Using the LoadTemplate function

• One way to ceate an EmailTemplate is by using the LoadTemplate function

from wholemail import LoadTemplate


# Lets create an email template class using the LoadTEmp
# load from a file
context = {"name":"Jane"}
template = LoadTemplate( html_file = "myfile.html"  ,context = context)

# load from text 
template = LoadTemplate(html_text = "<h1> {{name}} </h1>" ,context = context)

Working with the EmailTemplate class

• The EmailTemplate class represents the email you wish to send .
• It contains the text message or html code that will make up the email .
• Most importantly , it allows for customization . ie . You can add custom content and context
• You can also create a template using the LoadTemplate function
• Below is a demonstration is creating an EmailTemplate class :

from wholemail import EmailTemplate

# the EmailTemplate class can be sent via an EmailWorker class
# They simply represent the email you want to send
# Let's create a simple email template 

html = "<h1>Hello   {{name}}</h1>" # our html code in text form
context = {"name":"EaNasir"} # context that will be inserted into the html

template = EmailTemplate( html , context = context , name = "hello-email")

---

Working with the EmailWorker class

• The EmailWorker class is primarily used to send email templates and verify email codes

from wholemail import GmailEmailWorker , EmailCodeVerifier , EmailTemplate

# In this demonstration  ,  we will use the GmailEmailWorker
storage_folder = "data/"
my_email = "[e-mail]"
email_password = "dfujsdfv"

# initialize the worker object
worker = GmailEmailWorker(my_email , email_password , storage_folder = storage_folder)
 
# To send a template you just do this 
# Create an email template
html = "<h1>Hello   {{name}}</h1>" # our html code in text form
context = {"name":"EaNasir"} # context that will be inserted into the html
template_name  = "hello-template"
template = EmailTemplate( html , context = context , name = template_name)
# Prepare the recipient information
subject = "Saying hello" # subject of the email
recipient_email = "[e-mail]" # the email of the receiver

# send the template 
worker.SendTemplate( template , subject , recipient_email )

---

Sending a generic email verification email

• Email verification through a link sent to your email is a common practice across the web.
• The EmailVerificationEmailTemplate is an child of the EmailTemplate class that is made to simplify this common practice of verifying emails .
• Below is an example of loading the template
• Check out all preset templates here

from wholemail import EmailVerificationEmailTemplate

# Pre-set templates like EmailVerificationEmailTemplate make work easier when you want
# to send emails that involve the user clicking a link for verification purposes
# All you need is to provide some parameters and you are good to go
# EmailVerificationEmailTemplate is used to send an email with a link for the user 
# to click and verify their identity doing so 
# The common details like the verification link , company info , company address etc can be easily inserted,
# saving you the hustle

verification_link = "https://company.com/verification" # The link the user will click to verify their email
company_name = "Samsung"
recipient_name 	= "Mark"
email_verification_template = EmailVerificationEmailTemplate(
					recipient_name ,  # name of the recipient
					company_name, # company name
					verification_link , # The link for verification
					company_address = "Albuquerque", # address
					customer_support_link = "companysupport.com" , # a url for customer support
					company_phone_number = "+1234567", # company phone number +123
					company_website_link = "company.com", # company website url

					)

# Proceed to send the template using an EmailWorker class of your choice
my_email = "[e-mail]"
email_password = "dfujsdfv"
storage_folder = "data/"

#Lets use the GmailEmailWorker to send this email template
# initialize the worker object
worker = GmailEmailWorker(my_email , email_password , storage_folder = storage_folder)
# send the email template
worker.SendTemplate( template , "Email subject "  , "[e-mail]")

---

Sending a generic authentication code email

• Another common email is the verification code or one-time-password (OTP) email
• They are mostly used to authenticate an action on a website or a sign up process
• The CodeVerificationEmailTemplate class was built to make sending verification code emails much easier
• Here is an example of loading and sending the template

from wholemail import CodeVerificationEmailTemplate

# Pre-set templates like EmailVerificationEmailTemplate make work easier when you want
# to send common emails 
# All you need is to provide some parameters and you are good to go

# CodeVerificationEmailTemplate is used to send an email with a code to be
# used by the recipient for authentication purposes
# This type of email is very common

verification_code = '123' # A code to be used for authentication/verification

verification_code_email_template = CodeVerificationEmailTemplate(
					verification_code ,
					'JaneDoe', # reciients name
					company_name = "Company Inc", # comapny name
					company_address = "earth", # address
					customer_support_link = "company.com/company_support" , # url for customer support
					company_phone_number = "+3436536", # company phone number
					company_website_link = "company.com", # company website url

				)
# Proceed to send the template using an EmailWorker class of your choice
my_email = "[e-mail]"
email_password = "dfujsdfv"
storage_folder = "data/"

#Lets use the GmailEmailWorker to send this email template
# initialize the worker object
worker = GmailEmailWorker(my_email , email_password , storage_folder = storage_folder)
worker.SendTemplate( template , "Email subject "  , "[e-mail]")

---

Using the EmailWorker to authenticate codes

• If you wish to generate and authenticate codes sent to user emails , the EmailWorker class can be used to do so.
• Here is an example

from wholemail import GmailEmailWorker , EmailCodeVerifier , CodeVerificationEmailTemplate

# This is a demonstration of how to verify codes using the EmailWorker class
# We will use the GmailWorkerClass for this demo

my_email = "[e-mail]"
gmail_app_password = "dfujsdfv"
storage_folder = "data/"

# recipient information
subject = "Verification" # subject of the email
recipient_email = "[e-mail]" # the email of the receiver

# initialize the worker object
worker = GmailEmailWorker(my_email , gmail_app_password , storage_folder = storage_folder)

# Let us now create a code verifier and dictate ho we want the code to look like
file = "store_codes_here.txt" # where to store the codes
verifier = EmailCodeVerifier( 
				file ,
				length = 5 , # length of the code to be generated
				numbers = True , # to include numbers or not
				letters = True , # to include alphabetical letters or not
				punctuation_chars = True , # to include punctuation charachters or not
				casing = "upper" # Casing to use , you can choose between - upper , lower , all , the default is upper
						 )
# Let's generate a code we will send to the user
code = verifier.MakeNewCode(recipient_email)


# create and add the preset template made for code verification
template = CodeVerificationEmailTemplate(
					code , # A code to be used for authentication
					'JaneDoe', # reciients name
					company_name = "Company Inc", # comapny name
					company_address = "earth", # address
					customer_support_link = "company.com/company_support" , # url for customer support
					company_phone_number = "+3436536", # company phone number
					company_website_link = "company.com", # company website url
					name = "verification-template", # name of the template , optional

				)
# send the Email with the verification code information
worker.SendTemplate( template , subject , recipient_email )

# verify the code
is_valid_code = worker.VerifyCode(code)

# do something with the result

---

Using in a Django view

• If you use the Django framework, here is an example of using the wholemail library in a view .

# This is a demonstration of using wholemail in djnago

from django.http import HttpResponse , HttpRequest 

from wholemail import GmailSender

password , email = "123" , "[e-mail]"
sender = GmailSender(email , password)
html = '<h1>Hello</h1>'

# sending a text email in a view
def SendHelloEmail(request):
	user_email = "JohnDoe@domain"
	subject ="Subject is saying hi"
	message = "hi"
	sender.SendTextEmail(user_email , subject, message)
	# continue with yur code

# sending a html email
def SendHtmlEmailToUser(request):
	user_email = "JohnDoe@domain"
	subject ="Subject is this is html"
	message = "Alternative message"
	sender.SendHTMLEmail(user_email , subject,html , plain_message =  message)
	# continue with yur code

---

Adding Javascript and CSS code to the HTML of an EmailTemplate class

• If you can't write your Javascript and CSS in a html file and load it with a FileEmailTemplate , you can try using this method .

from wholemail import  FileEmailTemplate , EmailTemplate

# If you require Javascript or CSS code in your EmailTemplate , 
# you can simply add it in the context of an EmailTemplate

html_file = "myhtml.html"
# html file contents
'''

<!DOCTYPE html>
<html>
<head>
	<title></title>
</head>
<body>
<style>
	{{my_style}}
</style>
<script>
	{{my_javasscript}}
</script>
</body>
</html>

'''

javascript_code = 'function(){alert("Hello")}'
css_code = "body{color:black;}"
context = {
	"my_style":css_code,
	"my_javasscript":javascript_code,
}

# using the  FileEmailTemplate class
template = FileEmailTemplate(  html_file , context )

# using the EmailTemplate class
context = {"css":css_code , "js":javascript_code}
html_code = """<!DOCTYPE html>
<html><head>	<title></title>
</head><body>
<style>
	{{css_code}}
</style>
<script>
	{{js}}
</script>
</body>
</html>"""
template  = EmailTemplate( html_code , context  )


# just like that, the HTML will have the required extra code 

---

Changing preset email styles

• The preset email templates can be customized by using the template_style key word argument.
• This only works on preset templates , not FileEmailTemplate or EmailTemplate
• Here is an example :

from wholemail import EmailVerificationEmailTemplate , CodeVerificationEmailTemplate , TEMPLATE_STYLES_AVAILABLE

# Another way you can customize a pre-set template is by changing the style
# This is done using the prameter 'template_style:int = value'

# to see the availble template styles , do this
print(TEMPLATE_STYLES_AVAILABLE)

# lets specify the style of this pre-set template
verification_code = '123' # A code to be used for authentication/verification
verification_code_email_template = CodeVerificationEmailTemplate(
					verification_code ,
					'JaneDoe', # reciients name
					company_name = "Company Inc", # comapny name
					company_address = "earth", # address
					customer_support_link = "company.com/company_support" , # url for customer support
					company_phone_number = "+3436536", # company phone number
					company_website_link = "company.com", # company website url
					template_style = 1 , 
				)
# note that  we specified 'template_style=1'
# Make sure the number represents a valid style 

The End

• I wish you a fantastic time , thank you for checking this out . More is on the way . Thank you .

: )