@jkitching/msender v2.2.1

Msender – Create beautiful forms to interpellate decision-makers

Example & Demo

<div id="msender-container"></div>
<script>
/* Msender config params */
var msenderParams = {
  "to": [{
      "first_name": "London",
      "last_name": "Breed",
      "email": "major@sfgov.org",
      "format": "full"
    },
    {
      "first_name": "Eric",
      "last_name": "Garcetti",
      "email": "major@lamayor.org",
      "format": "full"
    }
  ],
  "bcc": [{
    "email": "cyberaction-copie@l214.com"
  }],
  "subject": "Vote YES! on Proposition 12",
  "message": "Dear Sir or Madam,\n\nPlease vote on California Prop 12.\n\nRegards,\n\n{{name}}",
  "filter_recipient": "manual",
  "filter_recipient_randomize": true,
  "step_two_title": "My representatives",
  "messengers": [
    "gmail",
    "applemail",
    "outlook",
    "thunderbird",
    "windowslivemail",
    "yahoo",
    "live"
  ],
  "locale": "en-EN"
};

/* wait for Msender to load and initialize */
window.addEventListener('msenderReady', function() {
  msender.renderContainer('#msender-container', msenderParams);
});
</script>
<script async src="https://unpkg.com/@l214/msender@2.2.1/build/bundle.js"></script>

➡️ See a demo

API

Event msenderReady (wait for loading)

It's recommended to load the Msender JavaScript file after other page assets (ideally using <script async>) for a better user experience. For that reason, it's necessary to wait for the MSender bundle to be loaded before calling its API.

window.addEventListener('msenderReady', function() {
  // window.msender is available
});

Initialize with renderContainer

msender.renderContainer(domElement, params);

• domElement (DOM element or string): The DOM element where Msender will be rendered. If a string is passed, it will be interpreted as a Selector and the first matching selector will be used.
• params (object): A JavaScript object (dictionary) containing the parameters (as described in the Parameters section below).

Parameters

to

A list of Recipients to send the email to. Can be filtered based on user inputs (see filter_recipient). See below for a full spec of the Recipient object.

Example:

[
  {
    "first_name": "John",
    "last_name": "Appleseed",
    "organization": "Apple Inc.",
    "email": "john@apple.com",
    "gender": "m",
    "format": "titlefull",
    "department_code": null
  }
]

cc

A list of Recipients to send the email to as cc.

bcc

A list of Recipients to send the email to as bcc.

Example:

[
  {
    "email": "cyberaction-copie@l214.com"
  }
]

subject

The email subject.

message

The email message. Can be templated with the following variables:

Example:

  {
    "message": "Hello, my name is {{name}}"
  }
]

filter_recipient

How the recipient list (the to parameter described above) should be filtered. Possible values are:

select_department

What French departments to show in the list. Possible values are:

step_two_title

The title to be displayed on step two (by default will display Destinataires).

enable_mailchimp

If enabled, a checkbox will ask user consent to subscribe to the newsletter (see send_mailchimp).

send_mailchimp

Initial state of the MailChimp subscription checkbox.

mailchimp_source

MailChimp source (by default msender).

locale

The locale (language and country) to use for internationalization. By default, it falls back to the browser's locale, or English (en) if not available.

The following language codes are currently supported: en, fr, de, es, pt, it, nl.

The UI elements are currently only translated in English and French. You can use the translations key to add custom translations.

Example:

locale: 'es-ES'

translations

Override the current translation strings or add additional languages.

Example:

translations: {
  es: {
    step_my_infos: 'Mi informacion'
  }
}

To get a list of all required strings for a new languages, see src/translations/en.js.

messengers

Email clients to enable. If not provided or null, all available ones will be included in the list.

Example:

messengers: [
  'applemail',
  'gmail'
]

Possible values are:

max_chars

Maximum number of characters (max length) allowed in the URL. This is useful to support long lists of receipients especially with online services (e.g. Gmail, Yahoo!) where URL is limited by the HTTP spec and servers.

If set, the list of recipients will be truncated to fit in the given length, with a minimum of 1 recipient.

Example:

max_chars: 2000,

max_chars_randomize

If set to true the list of recipients selected with max_chars will be randomized (instead of picking the first ones).

Example:

max_chars_randomize: true,

Recipient object

Possible gender values:

Possible format values:

Development

Prerequisites

• nvm (or npm > 8.10.0)
• Yarn

Install

nvm use
yarn install

Run

To start the development server:

yarn run start

Storybook

A React Storybook is available:

yarn run storybook

Test

Unit tests can be run with:

yarn run test

Build

To build a production ready bundle (in ./build/):

yarn run build

Publish on NPM

yarn run build && npm publish --access public

Roadmap

Generally speaking, we aim to make this codebase less specific to L214's use and less specific to the French environment (yay to a more international Msender!).

• Move away from CSS Modules and make it possible to have different themes (and override themes), so users can customize it to adapt to their style guidelines
• Filter by Department is very specific to France and should be made more flexible: either making it outside the project, or making a more generic "filter by region" with a country locale (French departments, US states, German Länder, etc.) (the field Recipient.department_code in not generic)
• Translate the Recipient titles (currently M. and Mme in French)
• Add the ability to add more custom email clients (to fit speicific users and country use-cases)

Email client specificities (2015 research)

Webmails specificities

• Hotmail : BCC can't be autocompleted with URL parameter
• Yahoo : subject can't be autocompleted with URL parameter; only one email adress per field can be passed with the URL parameters (emails seperation is done with JS so semicolons won't work)
• Free : body can't be autocompleted with URL parameter
• Orange, SFR, Laposte won't take any URL parameter

Misc info

• GET requests characters limitations by webmail:
• Windows Live Hotmail : ~1750 chars
• Gmail : ~1900 chars
• Yahoo Mail : ~7000 chars
• Client : ~1500 chars

• (limitations are after url encoding)

• Mail clients statistics for France pop :

• 1 - Orange => ~27%
• 2 - Hotmail/Outlook => ~19%
• 3 - Gmail => ~19%
• 4 - SFR => ~11%
• 5 - Yahoo => ~11%

Source : http://www.journaldunet.com/ebusiness/le-net/classement-services-mail/

• For mobile supports, only the client link will be displayed.

License

MIT License