HTML Logo by World Wide Web Consortium ( Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS, which is now in beta. ocPortal 9 will be superseded by Composr 10.

Head over to for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.

ocPortal Tutorial: Running a newsletter

Written by Chris Graham, ocProducts
You can use a newsletter to keep your users informed of news (for instance, those who do not check the site regularly).

Think carefully about how you wish to mix news, forum announcements or forum news, and newsletters for your site: in particular, you may wish to post more news than you send newsletters, or post to both news and newsletters, because news stays on your site in a permanent archive. You may also wish to prepare and use the same content for news as you do newsletters, so as to present a common message.

ocPortal newsletters

Important note

Newsletter subscription is distinct from membership, in that a subscription is solely tied to an e-mail address, and there is no tie between a subscription and a member account, and vice versa. This said, the newsletter subscription has special support for sending out newsletters to usergroup members regardless of whether they have specifically subscribed to a newsletter (it only shows usergroups that have at least one member in them with a configured e-mail address).
ocPortal newsletters support a concept of 'interest levels', which you can use to control sending of information, such that only subscribers with sufficient interest in your site get the most trivial newsletters, and all subscribers get the most critical newsletters. You may have multiple newsletters in ocPortal, for each of which members may choose to subscribe with an interest level of their choosing.

The interest levels feature is off-by-default, but even when disabled you may see it mentioned within the administrative interface. This is because if you ever do have it turned on you may accumulate members who chose an interest level, and you may make use of that data even if you no longer request new subscribers to set their interest levels (by disabling them again).

Thumbnail: Subscribing to the newsletter

Subscribing to the newsletter

Newsletter subscribers may use a password, chosen at subscription, to control their subscription settings. They may change their interest level for all newsletters, as well as remove interest totally. They may also have their password reset for the event that they lost it: this is only possible via confirmation of a reset, received via a link sent to the subscription e-mail address.

Newsletter signup

You will typically invite people to join the newsletter via the main_newsletter_signup block.
You can also have people signup directly via the site:newsletter module.

The newsletter process has a mandatory e-mail confirmation step so as to stop people signing up others to the newsletter, which may be illegal in some jurisdictions and is at least a nuisance.

When a user hits the block and subscribes through it, one of the following situations will happen:
  • A new subscription – ocPortal will sign them up and send a confirmation e-mail
  • An existing subscription never confirmed – ocPortal will treat this as a refresh to a new subscription, re-sending the confirmation e-mail
  • An existing subscription – ocPortal will show an error

The maintenace module is a bit richer:
  • A new subscription – ocPortal will sign them up and send a confirmation e-mail
  • An existing subscription never confirmed – ocPortal will treat this as a refresh to a new subscription, re-sending the confirmation e-mail (regardless of what password was entered)
  • An existing subscription, with the wrong maintenance password – ocPortal will give an error (with an option to re-set the password), unless you are logged in with a privileged account
  • An existing subscription, with the correct maintenance password – ocPortal will update the newsletter subscription

The block sets only for a single newsletter, and does not support subscription levels. The maintenance module can do for multiple newsletters at once, and does support subscription levels. This difference between block and maintenance page is intentional, as the block is intended only for new signups to a specific newsletter, not for changing existing subscriptions.

Sending newsletters

Newsletters are created using Comcode, and sent out in a dual format: both text and HTML. Most users will be able to read the HTML variant, as this is now by far the standard for common e-mail messages; however if they have this disabled, or an unusual e-mail client that cannot read HTML mails, then they will see the plain text version, which is your original Comcode.

Important note

You can use the WYSIWYG editor for making newsletters if you wish, but it is not advisable because plain-text readers will get some really ugly plain-text from it. If you make the newsletter using manual Comcode, the plain-text readers will see the Comcode, which is intrinsically easy to read.
When you send a newsletter you choose where to send it. Usergroups/newsletters with no members (to be precise, no members that can receive emails) will not be shown as options.

In order to change the newsletter appearance, to something more pleasing, you may wish to edit the NEWSLETTER_DEFAULT_FCOMCODE template. This is a template that defines the default newsletter, and hence you may fill it with Comcode to surround your actual newsletter text, such as to format your newsletter mails in an attractive manner. Also, the US CAN-SPAM act and the UK-equivalent (and likely many other laws in various countries) require you to include a physical address in your mailings, so you should include this in the template. You also are likely to want to edit the MAIL template, which defines how e-mails generally look. You will almost certainly want to edit these templates within the default theme, because if you are sending newsletters from the Admin Zone almost certainly the default theme will be the active theme when the newsletters are generated.

On the 'compose newsletter' screen there is a link to view newsletter subscribers. This will show all newsletter subscribers at all subscription levels.

When composing your newsletter you will be given a choice to send it out at a scheduled time. This is particularly useful for companies that need to coordinate a marketing plan.

Before your newsletter is sent, you have an opportunity to preview it, so you can ensure it is correct. Look at your preview carefully, as it is easy to make minor typographical or layout mistakes that would affect the professionalism portrayed in these bulk e-mails. You will also be e-mailed the newsletter during the preview stage so that you can perform the ultimate check.

If you have CRON enabled, once you proceed to send the e-mails to individual members will be put in 'drip' queue, and mails will be sent out on a cycle. This works around server limits and avoids overloading the server.

Sent newsletters

There is a newsletter archive available, so that you may browse through past newsletters, to make sure you present a consistent image, and generally keep track of what has been sent out in bulk for professional reasons.

What's new ('new content')

Thumbnail: Sending a 'new content' newsletter

Sending a 'new content' newsletter

A "what's new" feature for newsletter creation is supported. This simple system will automatically create a newsletter based on certain types of appropriate new content (downloads, for example) in the system since the last time such a newsletter was sent. You get the opportunity to edit the newsletter before it is sent, to add additional information and modify existing information such that your newsletter is appropriate.

In a similar vein, you may create newsletters from news. To do this, just visit the view page for the news that you wish to use and click the appropriate link. You will then be given the choice to refine the newsletter before it is sent.

For each content type supported, it shows only if there are less than 300 items that would be covered. If there are 300 or more, then it considers the content type too common to include and no items are shown.

Customised targeting

You may export the newsletter subscribers to a CSV file, change it somehow (using whatever strategy you like) and then choose to send out newsletters to your altered copy of the CSV file.

This can be used in many ways, such as:
  • Splitting up the subscribers, to do split testing
  • Manually removing competitors from the list
  • Picking out certain members from the newsletter list based on some kind of characteristic (you might use extra software to correlate this against another database in some way)
  • Migrating the subscriber list to another piece of dedicated newsletter software, or sending it to an expert newsletter design company for targeting

You can also import from a CSV file. ocPortal is quite flexible in supporting different layouts– it will try and auto-sense things.

Note that if you are using interest levels, each set of users with a different interest level should be stored in a different CSV file, as when you import them they would all be imported to the same one.

Templated newsletters

Want to take things to the next level with your newsletters? You can create full HTML newsletters, with embedded unsubscribe links, using newsletter templating.

Creating templated newsletters is best shown by example (this is the newsletter itself, fed into the field when you send the newsletter, or put inside the NEWSLETTER_DEFAULT_FCOMCODE template that prepopulates that field):


<html lang="{$LCASE*,{$LANG}}" dir="{!dir}">
<meta http-equiv="Content-Type" content="text/html; charset={!charset}" />
   {$,Try and figure out the best greeting from the data available - we prefer to welcome people by forename but we might not have it}
   <p>Dear \{+START,IF_NON_EMPTY,{forename}\}{forename}\{+END\}\{+START,IF_EMPTY,{forename}\}{name}\{+END\},</p>

   {$PARAGRAPH,{$?,{$IS_EMPTY,{CONTENT}},Your text goes here.,{CONTENT}}}

   <p>You're receiving this newsletter because you subscribed at some point. Not interested anymore? <a href="{unsub_url*}">Unsubscribe</a>.</p>
   <p>You're receiving this e-mail because you are a member on {$SITE_NAME*}.</p>

Note how the example includes the 'html' tag, etc – it is not a snippet, it is a full piece of HTML. This is optional, but if you do write your newsletters like this ocPortal will be clever enough to bypass wrapping the newsletter in the standard 'MAIL' template.

You have the following template variables available to you (beyond all the default capabilities of Comcode):
  • title, The subject line of the email (and also the equivalent of '{TITLE}' in the MAIL template)
  • forename, The forename of the subscriber (may be blank if it is not known)
  • surname, The surname of the subscriber (may be blank if it is not known)
  • name, The full name of the subscriber (either a combination of forename and surname, the members username, or the NEWSLETTER_SUBSCRIBER language string – depending on what data is available on the reader)
  • member_id, The member ID of the subscriber, or blank if there is no discerned member ID
  • email_address, The email address of the subscriber
  • sendid, A special code identifying the subscriber (starts with 'm' if it is a member, or 'n' if it is a newsletter subscriber)
  • unsub_url, A URL to unsubscribe from (one-click unsubscribe for newsletter recipients, a link to account settings for other recipients). If you are using unsub_url in a Comcode newsletter it is very important not to insert it plainly, as ocPortal will look at the link for a link caption and incidentally click that link for every user. Instead use a Comcode 'url' tag and hence tell ocPortal what caption to give the link.

If you are going to go down this path it is strongly recommended to tick (check) the 'HTML only' box when you go to send your newsletters, as the auto-generated text equivalents will not be easily readable.
The vast majority of email applications have HTML capabilities nowadays, so you are not really sacrificing anything if you do this.

This bit may confuse you: {+START,IF_NON_EMPTY,{forename}}{forename}{+END}{+START,IF_EMPTY,{forename}}{name}{+END}
It is saying "if the forename is available, use the forename, if the forename is not available, use the username".

Bounce filtering

There is a feature for removing newsletter subscribers that bounce e-mails (i.e. dead e-mail accounts). This stops noise coming back when you send out a newsletter, and increases the efficiency of future sends.

The removal process also removes the "allow staff e-mails" setting from members who have a matching e-mail address.

For this tool to work, you must have the PHP IMAP extension on your server.

You should manually move anything sent to your website e-mail address that looks like a bounce e-mail into a new bounces folder, and then run the tool upon that folder:
  • Go to the Admin Zone, then the Tools section, then the Newsletter icon
  • Select the "Bounce filter" icon.
  • Enter your server IMAP details.
  • Select your bounces folder (if ocPortal can see one that matches the word "bounce", it will be auto-selected). Note that if you select a folder with too many e-mail messages in (i.e. something that doesn't just contain bounce e-mails) then ocPortal could give you an error due to running out of memory

ocPortal will then show e-mail addresses found within e-mails in the selected folder, where it can find a matching newsletter/member account for an e-mail address. Any e-mail address attached to an e-mail that looks like a bounce e-mail will be auto-ticked (auto-checked). If you are confident the IMAP folder only contained bounces, you can tick (check) the remaining addresses.

If you proceed through, all ticked (checked) e-mails will be removed from the newsletter / have their "allow staff e-mail" member setting disabled.

Blocking senders

If you wish to create a list of e-mail addresses to never send to, you can do so by making an uploads/website_specific/newsletter_blocked.csv file. Put each e-mail address on it's own line. A CSV file with a single column is the same thing as a simple text file with one entry per line, so it's really simple to edit, whichever way you wish to work. The filter works behind-the-scenes between you choosing to send out your newsletter, and ocPortal actually sending it. If you have the filter successfully in place then ocPortal will confirm this with an "You have a uploads/website_specific/newsletter_blocked.csv file in place, blocking (number of addresses) e-mail addresses from receiving the newsletter." message on the newsletter authoring screen ("Send out issue").
The block list is useful for situations such as:
  • A previous send failed part-way-through for some reason, and you have a list of users you know it did get sent to already.
  • You maintain a manual list of users who have unsubscribed and you are very careful to not send to them, even if someone re-subscribes them.
  • You want to block a list of e-mail addresses you know belong to competitors.
You may add additional columns to the CSV file, which will be ignored. You can use this for keeping notes, for example. If you do this make sure you save as a true CSV file (comma-separated) though, not a TSV file.

See also