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.
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.
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.
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 theAccount 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 typeString
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 aNumber
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.
- appVersion
- 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.
- city
- 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 typeString
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.
Signature
Parameters
- contact - Contact information as contact object.
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.
Signature
Event object
- eventType
string
- A type of the event such asCustomer.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 typeString
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 aNumber
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 aString
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.
Signature
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.
Signature
Parameters
Accepts the same parameters as a MoonMail constructor or init
function
Returns
Returns MoonMail instance