Mailchimp Transactional API: Invoicing, Renewals — Bulk Sending emails in Flask!
Hey there! Welcome to my blog where I am documenting my journey as a self-taught developer.
If you are interested in implementing Mailchimp Transactional, you will need an API key from Mailchimp. To get an API key for the Transactional email, you must have a standard billing plan or higher. If you do not, this post may not be for you.
Please know, this is not a tutorial to follow. It is not going to give you a complete block of code to render results. There are preliminary steps that must be taken to get something such as Mailchimp Transactional API to work. This is an overview of the API and several specific use cases I will mention below. With that said…
Let’s get into it.
Mailchimp has two API’s for special use cases that extend functionality past the standard user account’s capabilities.
- Mailchimp Marketing
- Mailchimp Transactional (Formerly known as Mandrill)
We will be focusing on Mailchimp Transactional, specifically sending in bulk which is an odd use case, but there are times when this type of logic is the best option.
USE CASES: (When you do NOT have a subscription based email list. How do you reach your clients in an ethical — non-spamming way?)
- You have tens of thousands of clients that are coming up for a renewal during the same month.
- You have tens of thousands of clients that you need to notify of a business address change, phone number change, or some big news about your company. They all meet the same criteria.
- Perhaps there is a broker fee, a rate change or some type of adjustment in your terms & conditions at your agency, where a standard mailer won’t suffice. And you need to send in bulk a specific email template.
Of course, this is all considering these users have purchased on your web app prior, you have their email address and you are not spamming them with emails that they don’t want. This is to notify them of changes that will benefit them which they must be aware of.
After that lengthy introduction, about the use cases of Mailchimp Transactional, let’s see how to implement it in a Flask Route using Python.
The parameters will be for a query further in the function to pull every client that match a specific month of expiration, and whether or not they have opted in for paperless for their account.
The query and additional code in the loop is below:
Okay, so there is a lot going on here, but the only thing to take away…we query a Policy table from our db in a variable called “policies”, and iterate through it. Looking carefully, you will see the “to” array. We append every user’s email and their first name in a dictionary within the array. That is all you need to understand from the above code snippet.
Check out the message dictionary below in the next code snippet.
Let’s go through it.
to = []
The “to” variable is an empty array which will have users email addresses appended in, we just did that above, it received a dictionary.
text = “”
The “text” variable is a string which will have custom text in the subject line of the email based off of the recipients information.
message = {}
The important thing to note is the message dictionary. Mailchimp Transactional will need a dictionary to pass information to the API and in this case, we are giving it the variable name, “message”. Below are 8 keys in the message dictionary which will need values.
The docs for sending an email using an email template are here. Definitions below are taken from the docs.
from_email — The sender email address.
subject — The message subject.
text — Optional full text content to be sent.
to — An array of recipient information.
async — Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async.
merge —Whether to evaluate merge tags in the message. Will automatically be set to true if either merge_vars or globalmerge_vars are provided.
merge_language —The merge tag language to use when evaluating merge tags, either mailchimp or handlebars Possible values:
"mailchimp"or"handlebars".merge_vars — Per-recipient merge variables, which override global merge variables with the same name.
Let’s take a look at the merge_vars array! This is where the magic happens when sending bulk transactional emails. Merge_vars will allow us to make each email contain specific embedded variables to the clients that are receiving them. Variables will not be global, but client specific.
We are appending an object to the merge_vars array. This object is nested in the policies loop as you saw above. The original query ‘policies’ is using the letter ‘p’ as an iterator.
Therefore, we are taking the users email, the users first name, and the users invoice amount / premium (insurance jargon).
Things to note:
- The vars array contains key value pairs. The “name” key is important because this must match the handlebars templating language in the Mailchimp Transactional Email Template.
- The “content” key holds the variable value that will replace the “name” key in the email template.
Now, we send the information to populate the email template and send to our users in bulk. Code below.
I have os environment variables set up in my codebase to hide API keys.
We pass the key to MailchimpTransactional.Client().
And the response variable will take “mailchimp.messages.send_template({}).
We pass the template name which is important because that will dictate which template you use in your Mailchimp Transactional account.
And the message…well, if you recall we are passing that dictionary from above with all of it’s information!
The complete code screenshot is below.
If you want to send bulk email in Mailchimp, to users who have not officially subscribed to your email list, but have purchased or reached out prior, the Mailchimp Transactional email API is for you. It is powerful, and has the ability to send emails in bulk.
Happy Coding!
