Lesson 5&6: CiviMail

Mar 22, 2015 |

Mailings tab


  • Understand the difference between CiviMail and Send Mail action
  • Know how to set up CiviMail with your or the org’s email address
  • Know how to create, edit and format an email on CiviMail
  • Be able to set up cron for scheduled mailings
  • Be able to manage mailing subscribers
  • Be able to create mailing reports and keep track of open, click and bounce rates

What Is CiviMail And Why Use It?

Emailing is a huge part of constituent management because it’s the primary way of contacting and reaching out to your constituents nowadays. CiviMail is the CiviCRM component that deals with your emails. It helps you managing your emails, scheduling mass mailings, keeping track of the data of your mailings, etc. Of course, you don’t have to use CiviMail to achieve all that, however, CiviMail, being part of the CiviCRM system, integrates with other CiviCRM components, and has more advantages than a external mailing management system. Here are a few examples:

  • Whenever you add new contacts in a  mailing list Group, you don’t have to update CiviMail like you’d do for an external mailing system.
  • CiviMail allows you to set up autoresponses to replies from recipients
  • You will be able to create reports for CiviMail and keep track of subscribers, click and open rates, and more.

Ways to Send Mails Via CiviCRM

From the examples above, you might already have some idea of how CiviMail works. However, CiviMail is only one of the three ways to send mails through CiviCRM. Emails can also be done via the “Send Mail action”, which can be found through Actions>Send an Email in a contact’s profile or contact search results. Send Mail action is good for emailing a small group of individuals, and has some functions slightly different from CiviMail. The difference between CiviMail and Send Mail action will be illustrated more in the next section. The last but not the least way to send out emails through CiviCRM is by setting up automated emails. This will be mentioned more in the future lessons because it integrates other CiviCRM components, but here are two examples: 1) when you create an event on CiviCRM, you may set up a confirmation email or a reminder email for participants. The emails will be triggered when participants register online, or event date is approaching. 2) when people sign up for memberships, you may set up automated membership renewal reminders weeks or days before their memberships expire.

CiviMail v.s. Send Mail action

CiviMail and Send Mail action are both ways to send out emails via CiviCRM, however, they are slightly different in terms of functions and purposes. Below is a comparison of CiviMail and Send Mail action.

 Functions CiviMail Send Mail
1. Recipients To mailing lists groups, or to multiple contacts from search results* To one contact via profile or multiple contacts from search results *
2. Number of Recipients  More than 50  Up to 50
3. Tracking clicks and open rates  Yes No
4. Keeping record of mailings Archiving is available. Sent mails will be treated as an activity.
5. Replies Will file replies from recipient and can set up autoresponses to replies. Replies will not be recorded (unless it’s saved as an activity manually), and autoresponses is not available
6. Use of templates Yes Yes
7. File attachment Yes No
8. Creating a report Yes No
9. Unsubscription Recipients can only unsubscribe when in a mailing list. (can’t unsubscribe if it’s sent through search results and contact is not in a mailing list.) No unsubscription is available

*Both CiviMail and Send Mail action allow sending emails from search results. That being said, there are two different options for mailing under “Action” (see image below). Please make sure you know the difference and choose the correct option when you send out an email. Here is a link to the CiviCRM users book. I highly recommend you to read through if you want to learn more about CiviMail.mail1

Setting up & configuration

If you’re hoping to use Civi for any type of communications (mailings and such), then you’re going to have to set up Outbound Mail. This has a few different components, so it’s very important that you understand how these differnt parts interact.

Where Do Emails Come From?

Emails are generated by your domain’s mail server. There’s some computer stuff going on in there that we won’t get into (mainly because we don’t understand it) but bascially, your server has the ability to generate and send emails and CiviCRM taps into that ability. By default, any email sent from Civi will be generated by your server unless we go do some special stuff to get it to send from another mail server.

Configure “From Email” Address

CiviCRM allows you to have lots of From Email Addresses. That is, the address that people see mail and mailings coming from. There are lots of reasons for doing this. Some orgs like to have a new email address for each event they do. Like our friends at Aspiration had CATechFest2014@aspirationtech.org for their CA Tech Fest event last year and will have CATechFest2015@aspirationtech.org for it this year.

Before we can send emails with Civi, we’ll need to set up at least one From Address. Head on over to Administer > CiviMail > From Email Addresses. When you get there you’ll see the generic email address. Edit this to reflect the address you would like to use. Remember that you need to use the proper mail address format of having the name in quotes and then the address in carrots.


Configure Mail Account

Still not there yet. We have to specify an account to catch bounced emails when they happen. Go to Administer > CiviMail > Mail Accounts. Again choose to edit the generic account. We’re going to use an email address that you create for this domain. For instructions on how to do this, please refer to this blog post. Once you’ve created your new address, be sure to hit the “Configure Email Client” option and then scroll down to find the server name.


Input The Info

The following are the required fields and what they’re asking for.

  • Name: Doesn’t matter what you put, this is just the internal name your giving it
  • Server: The server you just copied when you made the email address. It will be something like cpsrv22.lithiumhosting.com
  • Username: The full email address you just created
  • Password: The word of pass
  • Email Domain: The part after the @ in your email address
  • Protocol: IMAP
  • Use SSL?: Yes. Check it
  • Used For?: Bounce Processing. We don’t know how to do the other thing yet.

Once we’ve got that all done with, you should be ready to roll! Well…partially.

Test Out Send Mail

You can send emails directly to individuals and small groups. Let’s send one to our friend Garrus Vakarian about how we need him to calibrate our computers. We just search for his name and when we’re on his contact page, hit Actions > Send an Email. What you get is fairly straightforward, but let’s break it down.


  1. From Address: By default, it will choose the email of the user who is signed in. This might be fine if you are intending to send an email as yourself as a staff member of the org, but remember it is never OK to send emails on behalf of an org from your personal email.
  2. Use Template: You can refer to the template section of this lesson, but briefly, if you ever send the same email twice, you should make a template. It will send you infinite time. You can just hit the Save as Template box at the bottom.
  3. Subject: You know what this is
  4. Insert Token: Put Tokens into the body of the email
  5. Editor: Write your email with the visual HTML editor. You can also click “Source” to edit the HTML

The Result


Creating an email

This section will be focused on CiviMail because mass mailing such as newsletters, event invitations or member-exclusive news will need more organizing and formatting than mailings to small groups of individuals. Before you begin writing an email, you need to understand how header, footer, body, and  images, is set up nicely, so lets start!

Header and Footer

Header and footer are important pieces of an email that wraps your main content. A header usually contains your organization’s logo, or a title. It could be an image, simple text, or a combination of both. Here is an example of a header:


On the other hand, footer usually contains information such as your organization’s address, website, other contact info, or unsubscribe options. Here is an example of  a footer:


Something worth noting about the footer is the difference between unsubscribe and opt-out options. To unsubscribe means to be removed from a mailing list, and to opt-out means to not receive any bulk emails. For example, I subscribe to a non-profit’s newsletter, Volunteer Opportunities, and Community Weekly Updates. If I unsubscribe to “Volunteer Opportunities”, I will still receive emails from the other two mailing lists; however, if I opt-out from bulk mailing, I will no longer receive emails from any of the mailing lists. Make sure you put them in the right place in your footer!

In other words, header and footer contains elements that won’t be changed frequently (similar to the static page of your website). A header or footer can be designed to be used for one specific type of mass mailing or multiple ones. For instance, you may create a header for Newsletters with an image title such as the UCSC Newsletter, or you may also create a header that only contains your organization name and logo for multiple occasions.

In order to add or edit your headers and footers on CiviMail, you need to go to “Administers> CiviMail> Headers, Footers, and Automated Messages“. You may choose to edit the existing one, or start one from scratch. It might be a little confusing because we haven’t talked about formatting and tokens, but we will get to it. So far you only need to know what headers and footers should contain, and how to edit or add one.


If you followed along the instructions and get to the “Headers, Footers, and Automated Messages” page, you will see that the existing header and footers contains something like this: {domain.address}. These are tokens, which, according to CiviCRM users book, “are placeholders that CiviCRM recognizes and replaces with an appropriate value when sending each message”. For example, when you receive an newsletter that greets you with your name, that is probably the {contact.first_name} token.

When creating an email, you will see a dropdown list on the side that says “Insert Token”. Click on it, choose the token you want to add, and it will be inserted with the correct format (see example here). When editing or creating headers and footers, you won’t see such options, therefore, you might want to refer to this page when you’re adding tokens for headers and footers.


CiviMail allows two types of email displaying options: HTML, or plain text. For plain text, it is like a text message that doesn’t allow any formatting. It is good for sending out simple and straightforward emails and communication on the individual level. You don’t have to have a plain text version of your mass mailing, but some people might choose to receive plain text emails rather than fancily formatted emails; in that case, make sure you have a plain text version to keep in touch with your minimalist subscribers. On the other hand, the HTML option allows emails to be formatted with HTML and CSS codes. You may create your HTML-formatted emails from scratch, or you may look for free templates online and try to work with it. On CiviMail, every element,whether it is the header, footer, email body or templates, allows HTML coding, and takes similar steps to complete. Therefore, I will show you the techniques and steps I take to format an email with free templates I found online, and you can be creative and apply all or parts of the steps when you are creating yours. Here are the steps:

Search and download free email templates online

For online free templates, I recommend Campaign Monitor because their HTML code works the best with CiviCRM. Campaign Monitor allows you to build your own templates or you can choose from 100+ free pre-made templates. Either way, you’ll have to download the templates to obtain the HTML and CSS codes.

Make sure your CiviCRM have a new template (Mailings>Message templates>Add Message Template) or new email (Mailings>New Mailing) opened up and ready for the next step.

Copy the HTML and CSS codes

In the folder that you extracted, you will see a HTML file, and a image folder, like this:


Some pre-made templates comes with more than one HTML file. You can open them all and decide which one you like, and keep that one open on your browser.


On the browser, right click, and click on “View Page Source”


Copy the codes. You can paste the codes somewhere else and keep a record of it, or move on to the next step.


Paste the codes to new email or template

Go to the new email or template that you opened, click on “Source” on the HTML editor


When the tool bar is disabled, paste your code in the box, then click on “Source” again


*The HTML code will indicate where the header and footer are. Since we are using the header and footer function in CiviMail, please cut those sections off to avoid repetitive information.*

Edit the content of your email

Now, your HTML box should show what your email will look like when you send them out, you can click and edit the content of your email. (Hint: The CiviMail header and footer will not be shown unless you use the preview function. )


You may find the images not working, please jump to the “Adding Image” section below and use the technique to add image to your email. (for pre-made templates, the images are in the “images” folder) This will take some work to replace the URLs, but once you’re done, you will have a great workflow when you send out mass mailings.

If you’re creating a new template, save the template. If you’re creating a new mails, move to the next step.

Send out a testing email (For new mails)

If you scroll down, you will see preview and send test mail options. If it the email looks amazing, you may send it to your subscribers!


Adding Image (Written by Thomas)

It’s worth thinking about where you’re going to be storing your images that Civi might use for headers, footers, and mailings. This section will take you through a real example of how this happens in the wild. We are going to:

  • Upload an image to our server
  • Find its URL
  • Make a new Mailing Header
  • Include the image in this new header
  • Send off a mailing with the new header

Where Will Your Image Live?

We advocate for keeping things all in the same place, so that if you’re trying to find something, you only have to look in one place. Since your CiviCRM instance is installed in WordPress, lets use that.

You’ve done this before in WordPress lab. Either in the sidebar or the top toolbar, choose Add Media.

Upload Your Image


Once you’ve uploaded the image you want, hit Edit. This will take you to the post editor screen for the image you just added. This isn’t the WP lab obviously, but FYI this is where you can edit image files that you’ve already uploaded to your server.


Copy the Image URL

Every image on every website has a web address, i.e. it’s own URL. Images are files, so it makes sense that they’de have an address doesn’t it? There on the image info window, highlight the image URL and copy it.


Create a New CiviCRM Header

OK so we’ve got our image up on the website, what are we going to do with it? The image I uploaded happened to be the Everett Program logo. I want it to show up at the top of all the mailings I send out so I’m going to use it in a mailing header.

To add a new header, go into your CiviCRM admin area, then find in the menu, Mailings > Headers, Footers, and Automated Messages.

Once you’re there you just hit the Add Mailing Component button. This is why we taught you HTML. If you don’t remember how to use any HTML, hit up Codecademy or consult W3Schools about creating an image.



In case your squinting, the HTML calls up the image using the URL I copied and then wraps it in an “a tag” to make the image into a link to the Everett homepage. Here’s the code, written on multiple lines for your convenience,

<a href="htttp://everettprogram.org>
<img  src="http://civiwp.icanfafsa.com/wp-content/uploads/2015/04/Everett-Logo-Transparent-Background.png" width="100%" />

You’ll also have to include a text version for people who don’t accept images.

Test It With A Mailing

We create a new mailing (addressed to a group of dummies of course), and when we get to the message editor, we can choose the new header. Send it out and let’s see what it looks like.


The Result



Free HTML Email templates:

Campaign Monitor (Template builder, or download from 100+ fancy templates)

CakeMail (Newsletter templates)

ZURB studio (Responsive templates)

Reports and Analyzing your mailings

Before your mail is sent…

When you send out a bulk mailing to your subscribers, you might want to see how many people really open your emails, click on the links, or unsubscription. Tracking those numbers is a good way to see how effective your bulk mailings are. You might send to one hundred of recipients and have only twenty clicks due to your unattractive title. In that case, you are only sending your messages out, but not making them visible to your audience. To track your open and click rates, make sure you click on both boxes in the “tracking” tab before you send out an email like so:


After your mail is sent…

To see the statistics of your bulk mailings, please look at the CiviCRM users Book section for reports and analyzing!

Schedule mails

In the previous lesson, we have learned much about how to make your CiviMail more efficient and fit your workflow, and now, we are going to take it to the next level–Schedule emails. Why? well, I believe we all have experienced drafting an email, and planning to send it a week later or so. And after you save that email to the draft folder, you will remind yourself, constantly, that you need to send that email out, but sometimes life is overwhelming and we really don’t have enough brain storage to remember that. Or, sometimes you might finish writing your email at 3 o’clock in the morning, but you don’t want to send it out right away because then people will know you are a little nigh owl that procrastinate till late and have to sacrifice the precious sleeping time to finish a simple task (well, that’s my case). You might have other reasons to schedule your mailings (like setting up reminders or invitations), but whatever the situation is, we can all appreciate scheduled emails  one way or the other. Without further ado, lets get to work!

Configuring Cron for Scheduled Mailings (written by Thomas Gelder)

Every Civi user encounters this problem: You create a mailing in CiviMail, send yourself a test, see that it’s good, schedule the mailing to go out at noon, and hit submit. Noon rolls around and nothing happens. Well what now?

CiviCRM is wonderful and amazing and we would never speak ill of it, but some things aren’t configured for you right out of the box. Some things “need” a systems admin to set up. Well we don’t have one of those, so we need to hack together the solution.

A Note About This Lesson Module

The solution outlined below is one way of solving the problem. It may not be (probably isn’t) the best solution, but it works, so we’ll go with it. If you are able to configure one of the other methods, we have a favor to ask. Please show us how! Everett is collaborative learning environment and we all have something to contribute. If you can understand the Managing Scheduled Jobs documentation on the wiki, then please let know and we can write up a walkthrough that is readable by non-developers.

Why Doen’t My Mailing Send?

The problem seems perplexing because you’re able to send emails under different circumstances. If you go to a contact’s page, you can send an email to them via the actions menu. Also, the test email step in CiviMail works no problem. So why doesn’t it work for your mailing?

Scheduled Jobs

Many web apps rely on a schedule telling them when to fire various “jobs”. You can think of jobs as an automated action performed by CiviCRM. To see the various jobs, you can check out the Managing Scheduled Jobs page on the wiki, or got to Administer > System Settings > Scheduled Jobs. All jobs are, by default, disabled. Every org has different needs, so Civi doesn’t enable everything out of the box and chew up server resources.

Executing a Job Manually

Let’s say you’ve got a mailing ready to go, but it won’t send out because we haven’t configured the scheduled jobs. I you go to Administer > System Settings > Scheduled Jobs scroll down to Mailings Scheduler then you’ll see that it’s disabled. Click edit and check the box asking if the job is enabled. This won’t make it run, but it will be necessary for actually fixing the problem. Once you’re back on the scheduled jobs page, click the more tab on the Mailing Scheduler box and then select Execute Now. This will trigger the mailing to send.

The Problem With This Method

Technically speaking, we accomplished what we wanted to: We got the mailing out. But we had to go and manually do something that should happen automatically. It’s like needing to jump start your car single time you want to drive somewhere. Aside from being inconvenient, it is suboptimal for the following reasons:

  • You Can’t Schedule Mailings: What if you have a mailing to go out at 5 o’clock on Friday, but you’ll be in Belize that day? We’ll you better reschedule canopy zipline journey because you personally gotta pull the trigger for your mailing.
  • You Can’t Schedule Multiple Mailings: Hitting Execute Now will fire every mailing job you have scheduled. So if you have multiple mailing lists to manage or want to get the next month’s worth of mailings up in a queue, you’re out of luck.

Doing it the “Right” Way

(I recommend you follow along the steps from here and complete the cron job)

A “cron job” is basically an action that is scheduled to execute at relative intercals. CiviCRM requires that you configure a “Cron Job” that will tell the jobs you’ve enabled that it’s ok to fire. There are several ways to do this, and if you can explain a different way please let us know, but we’ll be doing it in the most straight forward manner (i.e. the one I was actually able to figure out).

Prepare the Command

A cron job will “do a thing” periodically. We need to tell it what thing to do. The thing we’ll tell it to do is to execute CiviCRM jobs. If you did the manual job execution thing, you may have noticed that it takes you to a url and the jobs execute. Basically, we’re going to set up a command that will tell the server to go to this URL every time the cron runs.

Looking at the URL Method section of the Managing Scheduled Jobs page on the wiki, you’ll see the URL we need to visit. Choose the one that’s right for the CMS you have Civi installed on.





You’ll see that this is a dummy url. You’ll need to repalace a few things to make this work:

  • username
  • password
  • site-key

The username and password are the admin credentials for the CMS, the site key is the unique id of your CiviCRM installation that was generated when you installed CiviCRM. Use the file manager or an ftp client to find the file civicrm.settings.php.





Search for CIVICRM_SITE_KEY and you’ll find a very long string of random numbers and letters. Copy this and you’ve now got everything you need to create our command. In your text editor, take the url you’ve created and insert it into this:

curl '[URL]'

Write it exactly like that, with single quotes around the url. We have our command. let’s create the job

Creating the Cron Job

Now that we’ve got our command ready, we’re going to tell our server how often to do it.Log into your cPanel and navigate to Advanced > Cron Jobs. See how awesome you are? you’re in the Advanced tab!

  • Go down to Add a New Cron Job
  • Under -- Common Settings -- select Once Per Minute (* * * * *)
    • You should change this to something less frequent after we’ve confirmed that it worked so that you don’t chew up to many server resources
  • Next to Command paste in the command you made in the previous section.
  • Hit Add New Cron Job

Enable scheduled Jobs

The one last step is to go back to your CiviCRM, navigate to Administer>System Settings>Scheduled Jobs. Find the one says “Send Scheduled Mailings”, click on “more” on the very right side, and hit “enable”. You may take a look at other scheduled jobs and enable the ones you want to use, but for now, we are focusing on scheduled mailings. Now, everything is set up correctly, schedule a testing email, and make sure it works (if you don’t know how, we got you covered in the next section!).

Schedule a mailing

After you compose your email on CiviMail, click on “Next” at the very bottom, and you’ll be brought to step two:

smail1 When you’re done setting up the time, hit “Submit Mailing”:smail2You’ll be brought to a page that shows your mailing status:smail3


What is a profile?

According to the CiviCRM Users Book, “A Profile is a collection of fields from your database. Profiles are a powerful tool that have many different uses across all components of CiviCRM. Profiles are used to collect data (e.g., on a sign-up form), and to display data to the user (e.g., as a member directory). They can be used both internally (e.g., to create simplified data entry screens for staff) and externally (to display up-to-date information in from database). “

Still not quite sure what it is or how it looks like? Here are two examples:

For more details about profile and its settings and functions, please read the “Creating and managing Profiles” section in the Users Book. The following will be some steps that exemplifies the process of creating a profile:

[toggle title=”Creating a Profile”]

Go to Administer>Customize Data and Screens>Profiles, click on “add profile”, and enter the settings for your profile. If you are unsure of which does what, please refer back to the Users Book.



Then, add the fields of information that you want to include:


When you finish adding every field, you’ll be brought to a page that lists the field you created:


To use the profile you just created, you’ll have to create a new post or page on your WordPress and insert the profile.




Go to the page or post you created and check the result:


Posted in: Lab Lessons

Comments are closed.