Table of Contents

Mosaico Editor Overview

The heart of Mosaico is the WYSIWYG email editor, which you will use to configure templates for use in your mailings, as well as create and edit the mailings themselves.

The functionality in Mosaico is largely template-based, meaning the options available to you come from the templates themselves while the editor serves as the tool for manipulating them. There are several "base templates" for Mosaico that have various features, options, and layout choices that are arranged in "blocks" that you add to your email layout. You can then add content to and stylize your email or template however you'd like.

You can also customize the included "base templates" to be a "configured template" with your own font, color, and layout choices. These "configured templates" can then be used as a starting point for your mailing. Ideas for configured templates might be Monthly Newsletter, Member's News, Upcoming Events, etc. Additional functionality and options can be added by creating a custom "base template" for your organization, don't be afraid to ask us about this!

General Usage

Here are some general guidelines for using Mosaico to create or edit an email or email template in CiviCRM. Please note that some of the screen captures are from an earlier version of Mosaico, but the functionality remains the same.

Creating a Mosaico Template

As you normally would, navigate to Mailings > Mosaico Templates and select one of the Base Templates. We recommend the versafix-1 template for it's many layout options and features. Once you create a template or two, if you want to edit one of these Configured Templates this is the screen you would do that from.


Editing your email design and content

On the left side of the screen you'll see the layout "blocks" that will be used to build your email. Drag one of the available blocks from the left into the empty template on the right, add as many blocks of any format you need.


Hover over an image block and click the upload icon to add graphics


Select a block you’ve added to the template by clicking on it to change the look and feel. Clicking on the “Content” tab above the left hand column will allow you to control whether or not the title, image or button appear in the block:


Clicking on the “Style” button allows you to change the background and text colors, the font and the size of the text. You can switch between setting the style for the entire template or for just one block.

mosaico-editor-06.png mosaico-editor-07.png

Clicking inside the text in one of the blocks also brings up additional text formatting options:


Starting a new email

After you start a new mailing in CiviMail by going to CiviCRM > Mailings > New Mailing, you'll see a screen to configure the mailing name, subject, recipients, etc. Fill in all the required fields (including Recipients) and click Continue.


On the next screen you're prompted to select one of Mosaico's Base Templates, or one of your Configured Templates. If there are no Configured Template (like in the example shown below), we recommend the versafix-1 template for it's many layout options and features. But as you'll note, we've already created one Configured Template so let's pick that one.


After you pick your template, you're taken to the Mosaico editor, which is the same editor we covered above that you used to create the template originally. Here, you can make any edits that you want just for this mailing.

Note: any changes you make here will NOT be saved to your Configured Template. To do that, you must save this draft mailing and go to Mailing > Mosaico Templates to edit the template.

Testing your email

If you’d like to see what an email made with the template looks like, you can send a test message from the Mosaico editor by clicking “Test” in the upper right-hand corner of the editing screen:


A pop-up will appear. Enter the email address you’d like to send the test message to. Alternatively you can view the email in the browser:


Scheduling and sending your email

When you're done editing and testing your email, click the Close button in the upper right corner of the Mosaico email editor, the click the "Continue" button on the Design screen. This takes you to the Options screen where you can send the mailing immediately or schedule it for a future send.

Clicking the Advanced Mailing Options button will bring up a pop up where you can edit settings for attachments, tracking, publication to the web, etc. Although they look different in the Mosaico workflow, these features are covered the Mailing set-up screens section of the CiviCRM User Docs.

When finished you can click the Submit Mailing button or Save it as a draft for future use.

Editing Tips and Tricks

Editing the source code

Are you able to edit in the source code for an entire block? I see how to do so in an individual element, but not overall. For example, what if I want to add a drop shadow to a button? Would I be able to edit the entire box?

  • The source code for an entire block is not editable. However, you can add a content block that is only text and edit the source code/HTML to drop in whatever HTML code you would like, effectively editing the entire segment.

Adding a Table of contents

Adding a TOC automagically is not a feature that Mosaico supports. Also, the best practices information we have read indicates that since many email clients don't support anchor tag links (which is how a TOC is built), it's not necessarily a great idea to include them anyways. That said, you can manually create a TOC using the method described here. Alternatively, we have had great success by keeping the content of newsletter type emails to a short preview (with critical info) and linking out to a full version.

Adding an image to an existing text-only content area (block)

The limited WYSIWYG editor included with Mosaico does not appear to support adding an image to an existing text content block. There are work-arounds for this, which would include either editing the source code of a text-only block (not recommended) or just inserting the appropriate content block with image and moving the content from the text block by copying and pasting. We recommend having each "story" in your email contained in it's own content block, regardless of whether an image is included or not. Following this recommendation will allow your email layout to be more flexible, and if you need to add or remove an image the process is easier with each story or content item in it's own block.

Make columns within a text box?

This would be accomplished by selecting a multi-column block from the sidebar and adding it to your email, shown in this screen grab:


Next you would customize what content is shown in the block by clicking the "CONTENT" tab above the sidebar, revealing the options. You can also see here that you can fix the image height, which we believe means the two images are the same height. Un-fixing them might enable two different height images, Ginkgo Street hasn't tested this though.


Turning off everything leaves just the text, in two columns. There's another block that enables you to have a 3-column layout. What we have seen is that this doesn't allow for a "column 1 has an image and text BUT column 2 has a title and text" sort of scenario. It is our belief that this behavior is an example of Mosaico trying to "save you from yourself" by forcing some consistency in your content block layout and design.


Also, blocks don't seem to have the ability to "nest" inside each other, so you can't just drag an image block into a text block to add an image. If you started with a text-only block but wanted to add an image, you'd need to drag a block that has an image in it into the layout, then copypasta the text you started into the block with the image and upload the image.

Adding a drop shadow using HTML code

Ginkgo Street has successfully added a drop shadow to a table element be adding HTML code with CSS styles to a text-box in Mosaico. Basically just add a content block that is only text, edit the source/HTML, and drop the code.

Other Mosaico Resources

Updated: 3-21-2019