Newsletters Overview

by Justin Bodeutsch, Skyler Katz | Last edited: 1/11/2021

Module Overview

The newsletter module has the following features:

  • custom templates: supports the use of custom templates or "looks" for newsletters with varying layouts
  • scheduled send: ability to send newsletters at a scheduled time or immediately to specific groups of users or to all site members
  • read log: users can see which recipients have viewed the newsletter (this is not supported by all email clients)
  • unsubscribe: all newsletter include an unsubscribe link that allows recipients to easily opt-out.

Newsletter Templates

Newsletters have their own API for templates but can also use the Pages API. Any template setup for pages will theoreticaly work for newseletters, but will probably produce less than optimal results due to rendering issues with email clients.

Conventional naming of this template would be mcms_newsletter.php.

Here is a sample getContent that will be sufficient for displaying a newsletter in a template using the pages api:

getContent(
  "page",
  "display:detail",
  "find:".$_GET['nav'],
  "show:__text__"
);

 

Some things to keep in mind while building a newsletter template:

  • If you are using the page api - The __title__ tag is not used in the getContent
  • Sections can be assigned as with normal templates
  • Including the site nav is not recommended as the link will not function properly.
  • API calls
  • Tables tend to render better than divs in email clients
  • CSS should be used sparingly as it can be difficult to get consistent output over various email clients.

Subscribing to newsletters

A form can be added to sites that will allow members to enter their email address and have it be added it a group that the newsletter will go out to. A few notes:

  • If the email address already exists, their existing record will be added to the group. A new record is not created.
  • The success page will need to be manually created. The user will be taken there after the submit their address.
  • Users who have unsubscribed to the newsletter will not be able to re-subscribe via this method. Please submit a support ticket to have this done.
  • Typically, this signup is only able to capture a group to which the subscriber is added to and subscriber email address. However, there is a new "capture" parameter which will add first/last name functionality to the form—learn more on the Newsletters API page. 
  • If an image is not available, 'submitvalue' can be used instead to define the text of the submit button.
  • Anything in the "show" parameter will be shown directly before the form.

<?
  getContent(
    "member",
    "display:join",
    "group:newsletters",
    "submitimage:/images/submit.jpg",
    "show:<label>Newsletter Signup</label>",
    "success:/mailing-list/"
  );
?>

See the Newsletters API article for more information.