Configuring Cron for Scheduled Mailings

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

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.

WordPress

http://[SITEROOT]/wp-content/plugins/civicrm/civicrm/bin/cron.php?name=username&pass=password&key=site-key

Drupal

http://[SITEROOT]/sites/all/modules/civicrm/bin/cron.php?name=username&pass=password&key=site-key

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.

Drupal

[SITEROOT]sites/default/civicrm.settings.php

WordPress

http://[SITEROOT]/wp-content/plugins/civicrm/civicrm/bin/cron.php?name=username&pass=password&key=site-key

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. Don’t forget to change your cron job setting to every half or one hour to reduce the workload for your server!

Is It Working?

Depending on your host, the exact command may or may not work. For Lithium Hosting, curl seems to work fine. When testing this type of thing, I typically make new instances of whatever I’m testing on my personal website which is hosted on Lithium. Fortunate, since that’s what all of you use. The Everett site is hosted with a service called Site5 and when I went to implement this command, I found that it didn’t work! I Googled around using phrases like “Site5 Cron Job curl”. Eventually I found other people saying that the GET command instead of curl or wget would be the best bet. I did so and my next test mailing sent with no problem!

When you’re out in the field, things don’t always work the way you think they will. That’s why it’s important to learn to trouble shoot, problem solve, and aks someone more knowledgable when you are confronted with something not working.