Skip to content

Getting Started

Jump to bottom
Garrett Dimon edited this page Oct 5, 2016 · 20 revisions

Setup

  1. Install node version manager 
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.4/install.sh | bash
  1. Install and use node version specified from .nvmrc.
nvm install && nvm use
  1. Install Grunt CLI globally
npm install -g grunt-cli
  1. Install local dependencies
npm install
  1. Install premailer and nokogiri gems
gem install premailer
gem install nokogiri

  1. Create and edit config.json and secrets.json (Secrets are only necessary if you want to send test emails.)

  2. Start the build service that watches the src directory for changes and builds to dist.

npm start
  1. Open preview.html in a browser. It provides a normal width and mobile device width view of both the HTML and text versions of each email for easy previewing and scanning.

Configuration

There are two primary configuration files for MailMason: secrets.json and config.json. By default these files are ignored using .gitignore. Examples of these files are included at example_secrets.json and example_config.json. You can copy these files and rename them to create your own. The specific secrets and configurable values are documented within these files.

If you project is shared among team members, you may want to to update your .gitignore to recognize config.json so that each member of your team isn't forced to recreate it.

Secrets.json

By design secrets.json is ignored so that it's not accidentally committed. The base project includes an example_secrets.json that you can copy and rename in order to create your base secrets file. The relevant secrets are documented in the file.

If you're not sending test emails through Postmark and don't want to upload any images to a CDN, you don't have to provide values for these files.

Config.json

By default, config.json is ignored. The base project includes an example_config.json that you can copy and rename in order to create your base configuration file. The configuration file lets you set a variety of things like product name, sender name, corporate address, and various other strings. Each section and individual option is documented within the example_config.json file.

Images & Assets

Postmark doesn't currently provide hosting for images in templates. (It's on our roadmap, though.) So for the time being, if you'd like your emails to use images, you'll need to host these assets somewhere in order for them to show up. In general, we advise a subdomain of your primary domain for the emails. For instance, if you're sending email from [email protected], a great URL for the email assets would be assets.example.com.

Since images complicate things, they're off by default. If you turn them on, you'll need to upload the relevant images to a publicly available CDN so they can be displayed in the email. To do this, you'll need to provide information for your FTP server within config.json and provide the username and password for the FTP server in secrets.json. Once that's complete, you'll be able to upload all images from /src/images to the specified directory on your FTP server.

Once that's done, just add the value for the images_url within the config.json file. That URL will be used throughout to provide absolute references to the image locations.

Social Images

If you're using images, the templates can include logos and links for relevant social networks in the footer. If you're not using images, there won't be any social network links. In order for the social images to show up, you'll need to set use_images to true in the configuration file. Then you can provide the full URL for the social networks you use. For every URL you provide, the image and link will automatically be added. If you leave a social network URL blank, it will simply be ignored.

Finally, there are two versions of the social images for the footer. The first version is just the logos. The second version is circles with the logos cut out. There is a use_circles option in the config file as well. If you're only using a few social links, the original logos work best. However, if you have quite a few social networks to include, the logos begin to clash, and it looks better to use the circle versions.

Since the images have to be generated in advance, there's a limit to the social networks with built-in support. Right now, the following social networks are available:

  • Twitter
  • Facebook
  • Pinterest
  • Instagram
  • dribbble
  • Google+
  • YouTube
  • LinkedIn

Brought to yousss by

Postmark
Clone this wiki locally