Newspack Newsletters let you create email newsletters with the Gutenberg editor, and send them to your Mailchimp or Constant Contact mail lists, all without leaving your website.


Installing the plugin

Before using Newspack Newsletters, you will need to install and activate the plugin.

If you’re using Newspack, you will need to:

  1. Navigate to Dashboard > Plugins.
  2. Find Newspack Newletters listed in the plugins to install under Newspack.
  1. Click Install, then Activate.

If you are not using Newspack, you will need to download the Newspack Newsletters plugin, upload it to your WordPress site, and then activate it.


Adding API keys

Once the plugin is installed an activated, add the API keys for the different services Newspack Newsletters use:

  • MJML, which helps turn the markup generated by the Gutenberg editor into something that will display nicely in email clients.
  • Mailchimp or Constant Contact, which will act as your service provider and help send your emails.

Add your API keys by following these steps:

  1. Navigate to Dashboard > Newsletters, and click Add New.
  2. Select your Service Provider (Mailchimp or Constant Contact):
  1. If you pick Mailchimp, you will be prompted to enter a Mailchimp API key. To get this, you can log into your existing Mailchimp account, or sign up for a new one, and click the Generate Mailchimp API link below the text field. You can learn more about Mailchimp API keys here.
  1. If you pick Constant Contact, you will be prompted to enter a Constant Contact API key and Access token. To get this, you can log into your existing Constant Contact account, or sign up for a new one, and click the Get Constant Contact API key and Get Constant Contact access token links below the text field.
  1. Lastly, you will need to enter your MJML application ID and MJML secret key to the last two fields. You can requests these two keys here.
  2. Click Save Settings.

Now you’re ready to create newsletters! If you ever need to access these settings again, you can navigate to Dashboard > Newsletters > Settings to make changes.


Newsletter layouts

Newspack Newsletters comes bundled with four example layouts to use as a starting point for your newsletters. You can use these layouts, create and edit your own, or start with a blank slate!


Using layouts

When creating a new newsletter, you will be prompted to pick from existing layouts, or start with a blank editor:

  1. Navigate to Dashboard > Newsletters > Add New.
  1. Click the layouts thumbnails to view a full preview on the right. Each of the layouts includes instructional filler content, and will pull the logo you have set under Customizer > Site Identity for the newsletter header.
  2. Select the layout you would like to start with and click Use Selected Layout to start editing your newsletter.
  3. Alternatively, if you would like to create your own layout, click Start from Scratch to start with a blank editor.

Once you make your selection, you will be brought to the editor view of your newsletter, where you can make changes before sending.


Adding layouts

You can also create custom layouts to use for future newsletters. These can be based on existing layouts, or by starting from scratch:

  1. Just like you’re creating a new newsletter, navigate to Dashboard > Newsletters > Add New.
  2. Pick the layout you would like to start from, either an existing layout, or by clicking Start from Scratch.
  3. Use the editor to make any changes you would like to include in your custom layout.
  4. If you already already, in the top right corner, select the gear icon, and the Newsletter tab:
  1. Scroll down to the Layouts panel, and click Save new layout.
  1. Give your layout a descriptive name in the prompt that follows:
  1. Now the next time you create a new newsletter under Dashboard > Newsletters > Add New, your custom layout will be available in the My layouts tab on the left:

Editing layouts

Once you have added your own custom layouts, you can also edit them by doing the following:

  1. Navigate to Dashboard > Newsletters > Add New.
  2. From the layouts screen, pick the layout that you would like to edit from the My layouts tab, and click Use Selected Layout.
  3. Make any changes you would like to the layout.
  4. In the top-right corner, make sure you have the gear icon and Newsletter tab selected:
  1. Scroll down to the Layout panel, and click Update layout.
  1. Now your changes will be available the next time you select that custom layout. Note: they will overwrite the original layout; if you would like to keep the old layout, click Save new layout instead.

Resetting layouts

After making changes in the editor, you can roll back teh editor to your original selected layout by following these steps:

  1. In the top-right corner, make sure you have the gear icon and Newsletter tab selected:
  1. In the Layouts panel on the right, click Reset newsletter layout. Note: all of your changes will be lost.

Building newsletters

Getting started

To create a new newsletter:

  1. Navigate to Dashboard > Newsletters > Add New.
  2. Pick a layout to start with, or begin fresh by clicking Start From Scratch.

Newsletter options

When editing a newsletter, you will have a few more options that you usually would when editing a page or a post with Gutenberg.

Under the Newsletter panel on the right, you will have the following controls:

  • Subject – the email subject line for your newletter. By default, it will be the date you started composing your newletter.
  • To – displays the available mailing lists you have set up in your current service provider account (either the Mailchimp or Constant Contact account whos API keys were entered during set up).
  • From – the Name and Email the newsletter should appear to be from one a recipient’s inbox.
  • Preview text – the short line of text that will appear in your recipient’s inbox.
  • Disable ads for this newsletter? – if toggled on, will hide any newsletter ads you may have set up. Learn more about newsletter ads below.
  • Make newsletter page public? – if toggled on, will add the newsletter as a published page on your site once you’ve sent it, using a URL format like https://newspack.pub/newsletters/[newsletter-slug]. You can change the last part of the URL under the Permalinks panel; otherwise it will be based of of your newsletter’s subject.

Under the Styling panel, you will have the following controls:

  • Headings and Body font – allows you to change the header and body fonts in your newsletter to a different web-safe font.
  • Background color – allows you to change the background color of your entire email, either by using a color picker, or manually entering a hexadecimal value.

Under the Testing panel you will have the following controls:

  • Send a test to – a text field where can enter one or more comma-separated email addresses to send a test email to. You can use this field to make sure your email displays as expected before sending it out to a larger audience.

Under the Layout panel, you will have the following controls:

  • Save new layout – save your current editor changes as a new layout. Learn more.
  • Update layout – only available when you’ve started with one of your custom layouts, allows you to save changes to a layout you’ve already saved. Learn more.

And lastly, under the Permalink panel, you will have the option to change the last part of the URL used by your newsletter, should you choose to publish it to your website.


Available blocks

Newspack Newsletters supports several core Gutenberg blocks and their configurations, but there are some limitations to make sure the blocks display as expected in different email clients. The following blocks and block options are available:

  • Paragraph
  • Heading
  • List
  • Quote
  • Image (without the left and right alignment)
  • Buttons
  • Columns (can nest one level of blocks inside)
  • Group (can nest one level of blocks inside)
  • Separator
  • Spacer
  • Social Icons
  • And the Post Inserter block — it’s not a Core block, but a email-friendly version of the Homepage Posts block available in Newspack. The Post Inserter block lets you add posts to your emails; once they’re inserted they turn into regular header and paragraph blocks, so you can edit the post titles and excerpts to target them to your newsletter audience.

Sending newsletters

Once you are finished editing and testing your newsletter, you can click the Send button in the top right corner to send it to your selected mailing list.

If you have checked Make newsletter page public?, when you click Send your newsletter will also be saved as a public page on your website. It will always be available under Dashboard > Newsletters, too.


Newsletter Ads

Newspack Newsletters let you create ads that are automatically injected in your emails.

To add a Newsletter Ad:

  1. Navigate to Dashboard > Newsletters > Ads > Add New.
  2. The Ad title will not be displayed in the newsletter, so it’s good to give you ads descriptive names.
  3. Newsletter Ads use the block-based editor, with the same block restrictions as the newsletters.
  4. Once saved, ads will automatically appear in your newsletters, positioned as set by the Ad’s Approximate position setting in the Ad Settings panel on the right. You can also turn them off on a newsletter-by-newsletter basis, by checking Disable ads for this newsletter?