MoonMail JS Reference

This reference documents every object and method available in MoonMail’s browser-side JavaScript library, moonmail.js.

You can use moonmail.js’ APIs to bring data from your app or website into MoonMail, add new or update existing contacts, trigger event-based campaigns, and more.

Including moonmail.js

Include the moonmail.js script on the checkout page of your site — it should always be loaded directly from https://js.moonmail.io, rather than included in a bundle or hosted yourself.

<script src="https://js.moonmail.io/sdk/latest/moonmail.umd.js"></script>

Using moonmail.js as a module

We also provide an npm package, that makes it easier to load and use moonmail.js as a module.

npm i moonmail-js-sdk

MoonMail class

You can initialize an instance of MoonMail class using constructor or passing the same arguments to MoonMail.init function if you've included MoonMail SDK using HTML script tag.

const moonmail = new MoonMail({
accountId: 'YOUR_ACCOUNT_ID',
...otherOptions
});

Constructor options

  • accountId string required - MoonMail account ID. If you don't have a MoonMail account already, you’ll need to create one in order to use the SDK. Navigate to the general settings of your account and copy the Account ID
  • contact object - Default contact object. This contact information will be used in subsequent calls.

Contact object

  • address string - The unique identifier for the recipient. For example, an address could be a device token, email address, or mobile phone number.
  • attributes object - Custom attributes that your app reports to MoonMail. You can use these attributes as selection criteria when you create a segment. Attributes are bound to the contact. Attribute values must have the type String or be an array of strings. Attribute key cannot exceed 50 characters and include special character. Attribute value cannot exceed 100 characters.
  • metrics object - Custom metrics that your app reports to MoonMail. You can use these metrics as selection criteria when you create a segment. Metric values must be a Number type such as a float or integer. Metric key cannot exceed 50 characters and include special character.
  • demographic object - Information about contact's device, language and timezone
    • appVersion string - The version of the application associated with the contact
    • locale string - The contact locale in the following format: The ISO 639-1 alpha-2 code, followed by an underscore, followed by an ISO 3166-1 alpha-2 value, such as en_US
    • make string - The manufacturer of the contact device, such as Apple or Samsung.
    • model string - The model name or number of the contact device, such as iPhone.
    • modelVersion string - The model version of the contact device.
    • platform string - The platform of the contact device, such as iOS or Android.
    • platformVersion string - The platform version of the contact device.
    • timezone string - The timezone of the contact. Specified as a tz database value, such as Americas/Los_Angeles.
  • location object - Information about contact's location
    • city string - The city where the contact is located.
    • country string - The two-letter code for the country or region of the contact. Specified as an ISO 3166-1 alpha-2 code, such as "US" for the United States.
    • latitude number - The latitude of the contact location, rounded to one decimal place.
    • longitude number - The longitude of the contact location, rounded to one decimal place.
    • postalCode string - The postal code or zip code of the contact.
    • region string - The region of the contact location. For example, in the United States, this corresponds to a state.
  • optOut string - Indicates whether a user has opted out of receiving messages with one of the following values:
    • ALL - User has opted out of all messages.
    • NONE - Users has not opted out and receives all messages.
  • userId string - The unique identifier for the user. It will be generated automatically if not provided. One user might have multiple contacts, for example email and phone. If you provide the same userId those contacts will be linked to the same user.
  • userAttributes object - Custom user attributes that your app reports to MoonMail. You can use these attributes as selection criteria when you create a segment. User attributes are bound to a user instead of a contact and will be synchronized automatically between all contacts with the same userId. User attribute values must have the type String or be an array of strings.

moonmail.updateContact

Use this function to update contact information. If you initialize moonmail instance with a default contact information this function will update a default contact, otherwise you need to provide at least a contact address parameter.

moonmail
.updateContact({
attributes: {
hobbies: ['piano', 'hiking']
}
})
.then(function () {
console.log('done');
});

Signature

updateContact: (contact: Contact) => Promise;

Parameters

Returns

Returns a promise

moonmail.triggerEvent

Use this function to trigger custom events from you app that can be used to activate an event-based campaign. If you initialize moonmail instance with a default contact information this function will trigger events for the default contact, otherwise you need to provide at least a contact address parameter.

moonmail.triggerEvent('Customer.Purchase').then(function () {
console.log('done');
});

Signature

triggerEvent: (event: Event | Event[] | string | string[], contact?: Contact) => Promise;

Event object

  • eventType string - A type of the event such as Customer.Purchase
  • attributes object - Custom event attributes that your app reports to MoonMail. You can use these attributes to further specify when event-based campaign is triggered. Attribute values must have the type String or be an array of strings. Attribute key cannot exceed 50 characters and include special character.
  • metrics object - Custom event metrics that your app reports to MoonMail. to further specify when event-based campaign is triggered. Metric values must be a Number type such as a float or integer. Metric key cannot exceed 50 characters and include special character.

Parameters

  • event required - Information about a triggered event. Could be event type as a String or array of strings. You can also pass a full event object or an array of event objects.
  • contact - Additional contact information as contact object.

Returns

Returns a promise

moonmail.subscribeContact

Use this function to subscribe contact using a contact form. You need to create a contact form first and copy Form ID. An email confirmation will be sent to the contact address if it is configured in the form options.

moonmail.subscribeContact('YOUR_FORM_ID', {
address: 'email@example.com',
userAttributes: {
Name: 'John Doe'
}
});

Signature

subscribeContact: (formId: string, contact: Contact) => Promise;

Parameters

  • formId string required - Contact form ID.
  • contact - Additional contact information as contact object.

Returns

Returns a promise

moonmail.configure

Use this function to update accountId or default contact information.

moonmail.configure({
contact: {
address: 'email2@example.com'
}
});

Signature

configure: (config: Config) => this;

Parameters

Accepts the same parameters as a MoonMail constructor or init function

Returns

Returns MoonMail instance