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

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. 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.

POST https://client.moonmail.io/:accountId/contacts
curl --request POST 'https://client.moonmail.io/YOUR_ACCOUNT_ID/contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
"Address": "email@example.com",
"Attributes": {
"CustomerGroup": "VIP"
},
"Metrics": {
"TotalPurchased": 15000
}
}'

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

POST https://client.moonmail.io/:accountId/events
curl --request POST 'https://client.moonmail.io/YOUR_ACCOUNT_ID/events' \
--header 'Content-Type: application/json' \
--data-raw '{
"Contact": {
"Address": "email@example.com"
},
"Events": [
{
"EventType": "Customer.Purchase",
"Attributes": {
"CheckoutId": "12345"
},
"Metrics": {
"CartTotal": 1000
}
}
]
}'

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.
  • Events array required - A list of events to be triggered.
    • EventType string required - A type of the custom event such as Customer.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 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 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.

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.

POST https://client.moonmail.io/:accountId/subscribe
curl --request POST 'https://client.moonmail.io/YOUR_ACCOUNT_ID/subscribe' \
--header 'Content-Type: application/json' \
--data-raw '{
"Address": "email@example.com",
"FormId": "YOUR_FORM_ID",
"UserAttributes": {
"Name": "John Doe"
}
}'
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.