Subscription lists with MODX EmailResource

How to send email to users of your MODX site, using Bob Ray's EmailResource plug-in.

EmailResource is a plugin for the MODX Revolution Web content management system. It helps you to send users emails based on your Web content. In combination with a front-end form that collects users' email addresses, EmailResource can be the basis of a large and mostly automated subscription emailing system.

This is a detailed walk-through I created in the process of helping to specify and test EmailResource. For the technical details of configuring EmailResource, you should consult Bob Ray's EmailResource tutorial, because he's the guy who built EmailResource. (Bob also literally wrote the book on MODX Revolution.)

How EmailResource works

EmailResource does for email what the rest of MODX does for Web pages. It takes content from a MODX resource and layout from a template, combines them, and delivers the finished product to the right users. It will take Web content specified by you, makes its markup more email-friendly, put it in a specified HTML email template, and send it to the user groups you specify.

Before you start

Understand that gettng email to people is rather dramatically less simple than it looks. In particular, sending an email is no guarantee that your intended audience will receive it. See Jeff Atwood's amusing classic rant "So You'd Like to Send Some Email (Through Code)".

• To solve the spam problem, a lot of email gets filtered out along the chain joining you and your audience.
• To solve this problem in turn, firms in the chain have turned to systems such as DKIM, DomainKeys, SendID and Reverse PTR.
• Most webhosting firms have set up their webservers to serve pages fast. Rather fewer have set up their SMTP servers to pump out emails at the fastest possible rates.
• Email clients (programs that show people their emails) are much less standardised than Web browsers. Unless you are an expert or using a very good template, your email will look very different in an iPhone, a Blackberry, a Lotus Notes email client, Gmail, Outlook 2003 and Outlook.com.
• Because of these complications, several third-party services have sprung up that handle the task of maintaining email lists, formatting email, sending it and making sure it gets delivered. The best-known such full-service bulk email management services are MailChimp, Australia's own Campaign Monitor, and ConstantContact. Several other firms ("third-party delivery services") operate in the even narrower niche of just sending email and assuring its delivery.

Decide whether to use EmailResource

EmailResource was developed for subscription email services. It particularly suits:

• Developers who are using MODX's existing user management facilities, and want to send email to a defined group of users. Systems such as MailChimp will require you to maintain a user list outside MODX.
• Content managers who are combining existing MODX content into mailings such as newsletters. Automating your content is generally more reliable than having someone cut-and-paste into an outside email system, and you avoid having to log into another system.
• Designers and marketers who want their email to look broadly the ame in many email clients. EmailResource converts your CSS to "inline styles", which is the best way to ensure consistency of presentation in the many different email clients out there.
• Managers who want to send bulk emails without paying fees to third parties other than their ISP. All the third-party services will charge you for more than small amounts of mail.

You may not need EmailResource, and you may be better off without it:

• EmailResource is not super-complicated, but it is not as simple to use as MailChimp or Campaign Monitor. These specialist services have devoted enormous resources to creating easy-to-use interfaces. Your organisation may be better off just cutting and pasting text from your website into MailChimp or Campaign Monitor.
• However, MailChimp is known to reformat mail received through email beaming. You will need to check and possibly reformat your email if you use MailChimp, Campaign Monitor or any of their rivals.
• As described above, EmailResource will not ensure your emails are delivered, rather than blocked as spam. That's up to you and your webhost. The third-party delivery services have devoted enormous resources to making sure your emails get delivered.
• EmailResource will not report on your emailings. Third-party services will report - imperfectly - deliver, open and bounce rates.
• These rates, especially bounce rates, are fundamentally inaccurate. However, any data is better than none, provided you understand its imperfections. Even imperfect open rates are fine if you are comparing open rates on two email sent a week apart to the same user base.
• The EmailResource sending system has a few quirks. Notably, you send an email by previewing it from the MODX manager.
• MailChimp and Campaign Monitor, in particular, offer many integrations with other systems such as Salesforce and Google Apps For Your Domain (see the MailChimp integration list here). These integrations can be very powerful. And if MailChimp integration is central to your whole CMS implementation, rival CMS Drupal offers a tightly integrated MailChimp module.

Choose a mail delivery option

You have three main options for delivering the email you send with EmailResource. Choosing the right one will affect the cost of your email and your success rate in having that email delivered.

• Use your webhost's email server. This is an adequate solution for many and may be a good solution if your webhost has configured its servers for mass email and offers the key email verification facilities (DKIM, DomainKeys, SendID and Reverse PTR).
• Using your own emailing system works best when your webhost's email servers are properly configured. The system you set up will deliver best results if your webhost:
• is willing to work with you;
• is reliable; and
• has configured their email server well for email despatch.
• Webhosts are touchy about mass emailing. If you want to be certain your host will keep sending the mail, get a written agreement from them.
• If you are using Gmail's SMTP service or Google Apps For Your Domain to provide email, you should send your mass mailings from a separate domain or subdomain with its own CNAME record. This is because:
• Google has an email sending limit of 2000 messages per day. If you have a list expected to grow above this size, your emails may end up being blocked temporarily by Google.
• Sending via Google will make it impossible to configure a Reverse PTR record. (Technical explanation: the PTR record should match the SMTP response on port 25 when the receiving server sends back a verification check; this won't happen if Google is your SMTP provider.)
• Use a third-party mail delivery service. These handle the sending of email. They are specialists who can be relied upon for excellent email verification and good relationships with spam-filtering organisations and the key email providers such as Google, Hotmail and major (particularly US) ISPs.
• If Google, Yahoo, or any other major email service ever decides you are spamming their users and blacklists you (so that customer@gmail.com and loyalreader@yahoo.com suddenly and silently stop receiving your mailings), these services will do the work to get the blacklisting lifted. Blacklisting risk is a non-trivial issue in email delivery. You should assess it carefully before deciding against a third-party service.
• Most third-party delivery services provide reporting - however imperfect - on deliverability of draft email, and delivery rates and bounces from sent mail.
• The most reputable third-party delivery services are:
• SendGrid
• SMTP.com
• Amazon Simple Email Service (Amazon SES)
• Elastic Email (not so well known to me, but cheap)
• Use a specialist full-service bulk email management service.
• MailChimp offers all of the benefits of the third-party email delivery services listed above, along with some extras.
• MailChimp offers an "email beamer" facility: you send an email to them and they recreate it as a MailChimp draft which you can send from MailChimp. This is very convenient if you just want to use EmailResource to assemble your email text. (Indeed, assembling your email was all that the first version of EmailResource did.)
• You can also assemble your email using EmailResource and then cut-and-paste it into an application from another full-service bulk email management service such as Campaign Monitor.

Install EmailResource

EmailResource is a MODX plug-in, so it runs from within MODX. You download and install EmailResource using MODX's Package Managment system (System -> Package Management in the MODX top menu bar).

Once installation is complete, reload the page and you'll have a bunch of new MODX template variables, chunks and snippets, as well as one new plug-in (called EmailResource) visible in MODX's left-hand menu.

At this point you should choose - or more likely, create - at least one template to use for your emailings. You can leave it blank for the moment.

Set up EmailResource

Before you use EmailResource, you have to tell it about the email you want to send. Setting are in at least five places:

• One-time set-up parameters are set in the Properties tab of the EmailResource plug-in. All of them have sensible defaults, bt it is worth reviewing them. These parameters are:
  • Names and addressses for the party sending the email - that's you. These are set by default to the "emailsender" system setting - the email address you provided when you set up MODX.
    • Check the setting in the MODX top-of-page menu under "System -> System Settings" to make sure these are what you want, and change them if they're not. 
  • The email subject line. By default, this will be the longtitle of your email page, or the pagetitle if the longtitle is empty.
    • In most cases, you'll want to use the email resource's longtitle to set the email subject, so this can be ignored and left blank.
  • The list of templates which can be used for emails. By default, any template can be used, but your mailing will run more quickly if you use this setting to limit the templates used.
• Per-template parameters are set in the Template Variables tab of the template you use for your emailings. This is important to understand - the templates for your email contain many of the settings which determine how your email is sent. If you have more than one type of email that you want to send, create more templates. You can think of EmailResource templates as being like different email publications. If you have one newsletter on philosophy and another on gardening, create two templates.
• The template's Template Variables tab also controls which of the parameters are controlled as individual email parameters (see below).
• If you are drawing material from existing web pages into your email publication automatically, the template is usually the best place to put the automation code.
• Individual email parameters are set in the Template Variables tab of the resource you use for each emailing, though most of these are inherited from the per-template parameters. You can think of a  individual EmailResource resource as determining the shape of individual editions of your email publication. You can set up a new resource for each edition. In some circumstances, particularly if most of your material is automatically drawn from your website, you may be able to maintain a single resource for a publication and replace the non-automatic content each week.
• Final subject line and actual email content are set in the email resource itself.
• If you are drawing material from existing web pages into your email publication automatically, you will also need to flag on individual resources whether they are fresh content or not (see below).

Set up a system for flagging email content

Once you have EmailResource running, you'll need a way to flag content that should go in your email. The simplest way to achieve this is with a check-box for each article, or at least for all articles off a particular type. And the way to achieve that is with a template variable:

• Set up a new template variable - I call mine tvEmailYes.
• In the "input Options" tab, set the Input Type to "Check box" and the Input Options Value to "Email this article==1" (without the quote marks).
• In the "Template Access" tab, tick all the templates which might be used to create an article you'll later want to email.

Now when you create your email template, you can simply call any resource where tvEmailYes is set to "1"".

Once you've sent email, you'll need to untick all these check-boxes. However, note that Bob Ray's ResetCounters snippet will do this for your automatically. Just create the snippet and then call it using an unpublished page (clearly titled something like "Clear article email fields"). To blank all the check-boxes, just view that unpublished page from the manager.

Report on EmailResource

You can track your email-sourced traffic with Google Analytics (alternative 1) (alternative 2)

Using MODX's full power with EmailResource

The steps again:

• Create templates
• Collect users (and use double opt-in to ensure they really want your email).
• Flag the website content you want automatically included in your mailing.
• Assemble your site content automatically.
• Email to your user group.

A final note on bulk emailing

If you're just starting out with bulk emailing, you may not be fully aware of the sensitivity around the issue. Be aware: most bulk emailing is spam, so people are wary of it. If you're sending bulk email, you have a special duty to make sure that all of it is wanted email from a legitimate source.

To fulfil that duty, stick to best practice bulk emailing guidelines. The best starting point is Google's Bulk Senders Guidelines. In particular, you should:

• Use the verification methods mentioned above (DKIM, DomainKeys, SendID and Reverse PTR).
• Implement a double opt-in process for any email where the user is not paying specifically to join a list.
• Make unsubscribing a simple process.

Unsolicited bulk email - spam - is a blight on the Internet. The people behind MODX and EmailResource do not want it used to spam people. Thankfully, the problems EmailResource solves - sending lots of content to registered website users - are not the problems that spammers face.