Importing Segments

With MoonMail, you can define a user segment by importing a file that contains information about the contacts who belong to the segment. Importing a segment is useful if you define contact segments outside of MoonMail but you want to engage your contacts with MoonMail campaigns.

Unlike the dynamic segments that you create with the segment builder in the dashboard, an imported segment is an unchanging set of contacts:

Contact

A destination you can send messages to, such as an email address, mobile device identifier, or mobile phone number. A contact definition can include attributes that describe the user or device that you send messages to.

You can define a segment by importing a list of contact definitions. MoonMail creates the segment, and it updates any contacts that you previously added to MoonMail with the new information.

An imported segment consists of contacts. When you use MoonMail to send a message to the segment, the potential destinations include each contact that you list in the imported file.

When you create a new segment, you can use an imported segment as the base segment. You can then apply filters to the base segment to refine it according to your needs.

Imported segment considerations

Consider the following factor when you create imported segments:

  • If you create a campaign that sends messages when certain events happen, you can't use imported segments. Event-based campaigns can only use dynamic segments. For more information about creating dynamic segments, see Building Segments.

Segment import files

You define the contacts that belong to your segment in a comma-separated values (CSV) file. Then, you import the file into MoonMail to create the segment.

When you import a segment, remember the following:

  • MoonMail can't import compressed files.
  • The files that you import must use UTF-8 character encoding.
  • If you're importing new contacts, the Address attribute is required.
  • Your contact definitions can include only certain attributes. For a list, see Supported Attributes. In addition, an attribute name has to be 50 or fewer characters. An attribute value has to be 100 or fewer characters.

Example of a segment import file

You can import contacts that are defined in a CSV file, as in the following example: 

Address,UserAttributes.Name,UserAttributes.Surname,Location.Country,Location.City
email@example.com,John,Doe,USA,New York
email2@example.com,Jane,Doe,USA,San Francisco

The first line is the header, which contains the contact attributes. For a complete list of possible attributes, see Supported Attributes.

The subsequent lines define the contacts by providing values for each attribute in the header.

To include a comma, line break, or double quote in a value, enclose the value in double quotes, as in  "aaa,bbb". For more information about the CSV format, see RFC 4180 Common Format and MIME Type for Comma-Separated Values (CSV) Files.

Importing a segment

You can create an import segment in MoonMail uploading the file directly from your computer. However, you can import only 10 files at a time, and you can only upload files that are smaller than 1 gigabyte (GB).

To create a segment

  1. Sign in to your MoonMail account.
  2. Choose the Segments section. The Segments page opens and displays segments that you previously defined.
  3. Choose Create segment.
  4. Under Create a segment, choose Import a segment.
  5. Under File to import, click the upload area to select a CSV file from your computer or drag the CSV file into the upload area. Once you have uploaded the file you will a preview of the first five rows. Under Change fields mapping, you can rename or skip attributes you want to import. Choose from the list of existing attributes or create a new attribute with the following format: Attributes.[AttributeName] or UserAttributes.[AttributeName]. For example Attributes.Gender.

  6. When you upload files to MoonMail, you have to provide a segment name for the file you are importing. Under Segment name, enter a name for the file that you want to import.
  7. Note
    • By default, MoonMail provides a segment name that is equal to the name of the imported file but without the file name extension. You can change these default values to any name.
  8. When you finish, choose Create segment.

Supported Attributes

The table in this section lists and describes the attributes that you can specify in contact definitions that you import into MoonMail. The headers in the CSV file used to import the segment should match the names shown in the Attribute column.

You can replace attribute names that are shown as custom_attributewith any value. For example, if you want to store users' first and last names in attributes namedFirstNameandLastName, you can create custom attributes namedUser.UserAttributes.FirstNameandUser.UserAttributes.LastName, respectively. An attribute name can contain up to 50 characters. An attribute value can contain up to 100 characters. Attribute names are case sensitive.

Attribute Description
Address The unique destination of the contact, such as an email address, a mobile phone number, or a token for push notifications. Only email addresses are valid for now.
Attributes.custom_attribute A custom attribute that describes the contact. You can use this type of attribute as selection criteria when you create a segment. You can replace custom_attributewith any value. You can specify up to 20 custom attributes per contact.
ChannelType The channel to use when sending messages to the contact. For now, only EMAIL is available which is the default value. 
Demographic.AppVersion The version number of the application that's associated with the contact.
Demographic.Locale The locale of the contact, in the following format: the ISO 639-1 alpha-2 code, followed by an underscore (_), followed by an ISO 3166-1 alpha-2 value. For example, en_US is the English language locale for the United States.
Demographic.Make The manufacturer of the contact device, such as apple or samsung.
Demographic.Model The model name or number of the contact device, such as iPhone or SM-G900F.
Demographic.ModelVersion The model version of the contact device.
Demographic.Platform The operating system on the contact device, such as ios or android.
Demographic.PlatformVersion The version of the operating system on the contact device.
Demographic.Timezone The contact time zone, as a tz database value. For example, America/Los_Angeles for Pacific Time (North America).
Location.City The city where the contact is located.
Location.Country The two-character code, in ISO 3166-1 alpha-2 format , for the country or region where the contact is located. For example, US for the United States.
Location.Latitude The latitude coordinate of the contact location rounded to one decimal place.
Location.Longitude The longitude coordinate of the contact location rounded to one decimal place.
Location.PostalCode The postal or ZIP code for the area where the contact is located.
Location.Region The name of the region, such as a state or province, where the contact is located.
Metrics.custom_attribute A custom numeric metric that your application reports to MoonMail for the contact—for example, the number of sessions or number of items left in a cart—to use for segmentation purposes. You can replace custom_attribute with any value. You can specify up to 20 custom attributes per contact. These custom values can only be numeric.
User.UserAttributes.custom_attribute A custom attribute that describes the user. You can replace  custom_attribute with any value, such as FirstName or Age. You can specify up to 20 custom attributes per contact.
User.UserId A unique identifier for the user.

You can create as many as 40 custom attributes for contacts in your MoonMail account.