Client API
You can use MoonMail Client API to bring data from your app or website into MoonMail, add new or update existing contacts, trigger event-based campaigns, and more.
This API does not require authentication and can be used client side. You'll only need your MoonMail account ID.
Get your account ID
If you don't have a MoonMail account already, you’ll need to create one in order to use the Client API. Navigate to the general settings of your account and copy the Account ID
Endpoints
- POST https://client.moonmail.io/:accountId/contacts
- POST https://client.moonmail.io/:accountId/events
- POST https://client.moonmail.io/:accountId/subscribe
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. User attribute key cannot exceed 50 characters and include special character. User attribute value cannot exceed 100 characters.
note
If you are using MoonMail JS SDK all object attributes will be lowercase instead of capital case.
Create or update contact
Update existing contact information, if contact does not exist yet, it will be automatically created.
- cURL
- Node.js
- PHP
Parameters
- Address
string
required
- The unique identifier for the recipient. For example, an address could be a device token, email address, or mobile phone number. - All other parameters from the contact object.
Returns
Returns {Accepted: true}
or validation error.
Trigger event
Trigger custom events that can be used to activate an event-based campaign. If you provide additional contact attributes, the contact will be updated
- cURL
- Node.js
- PHP
Parameters
- Contact
object
required
- A contact object.- Address
string
required
- The unique identifier for the recipient. For example, an address could be a device token, email address, or mobile phone number. - All other parameters from the contact object.
- Address
- Events
array
required
- A list of events to be triggered.- EventType
string
required
- A type of the custom event such asCustomer.Purchase
. Cannot include special characters and start with_
character. - 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. Attribute value cannot exceed 100 characters. - 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.
- EventType
Returns
Returns {Accepted: true}
or validation error.
Subscribe contact
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.
- cURL
- Node.js
- PHP
- HTML Form
note
You can use HTML form to subscribe new contacts. If you want to pass additional attributes or metrics you need to use input names with square bracket notation, for example UserAttributes[Name]
or Attributes[CustomerGroup]
.
Parameters
- Address
string
required
- The email address of the recipient. - FormId
string
required
- MoonMail contact form ID. You need create a contact form to get it. - All other parameters from the contact object.
Returns
Returns {Accepted: true}
or validation error.