Create File Segment

curl --request POST \
  --url https://api-{dc}.moengage.com/v2/custom-segments/file-segment \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "custom_segment_unique_name",
  "attribute_name": "unique_identifier",
  "attribute_type": "string",
  "file_url": "https://s3.amazonaws.com/Sample_GAIDs.csv",
  "callback_url": "http://example.com/moengage-callback",
  "emails": [
    "user1@example.com",
    "user2@example.com"
  ],
  "expiry_time": 30
}
'

import requests

url = "https://api-{dc}.moengage.com/v2/custom-segments/file-segment"

payload = {
    "name": "custom_segment_unique_name",
    "attribute_name": "unique_identifier",
    "attribute_type": "string",
    "file_url": "https://s3.amazonaws.com/Sample_GAIDs.csv",
    "callback_url": "http://example.com/moengage-callback",
    "emails": ["user1@example.com", "user2@example.com"],
    "expiry_time": 30
}
headers = {
    "Content-Type": "<content-type>",
    "Authorization": "Basic <encoded-value>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': '<content-type>', Authorization: 'Basic <encoded-value>'},
  body: JSON.stringify({
    name: 'custom_segment_unique_name',
    attribute_name: 'unique_identifier',
    attribute_type: 'string',
    file_url: 'https://s3.amazonaws.com/Sample_GAIDs.csv',
    callback_url: 'http://example.com/moengage-callback',
    emails: ['user1@example.com', 'user2@example.com'],
    expiry_time: 30
  })
};

fetch('https://api-{dc}.moengage.com/v2/custom-segments/file-segment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-{dc}.moengage.com/v2/custom-segments/file-segment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'custom_segment_unique_name',
    'attribute_name' => 'unique_identifier',
    'attribute_type' => 'string',
    'file_url' => 'https://s3.amazonaws.com/Sample_GAIDs.csv',
    'callback_url' => 'http://example.com/moengage-callback',
    'emails' => [
        'user1@example.com',
        'user2@example.com'
    ],
    'expiry_time' => 30
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-{dc}.moengage.com/v2/custom-segments/file-segment"

	payload := strings.NewReader("{\n  \"name\": \"custom_segment_unique_name\",\n  \"attribute_name\": \"unique_identifier\",\n  \"attribute_type\": \"string\",\n  \"file_url\": \"https://s3.amazonaws.com/Sample_GAIDs.csv\",\n  \"callback_url\": \"http://example.com/moengage-callback\",\n  \"emails\": [\n    \"user1@example.com\",\n    \"user2@example.com\"\n  ],\n  \"expiry_time\": 30\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("Authorization", "Basic <encoded-value>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-{dc}.moengage.com/v2/custom-segments/file-segment")
  .header("Content-Type", "<content-type>")
  .header("Authorization", "Basic <encoded-value>")
  .body("{\n  \"name\": \"custom_segment_unique_name\",\n  \"attribute_name\": \"unique_identifier\",\n  \"attribute_type\": \"string\",\n  \"file_url\": \"https://s3.amazonaws.com/Sample_GAIDs.csv\",\n  \"callback_url\": \"http://example.com/moengage-callback\",\n  \"emails\": [\n    \"user1@example.com\",\n    \"user2@example.com\"\n  ],\n  \"expiry_time\": 30\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-{dc}.moengage.com/v2/custom-segments/file-segment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["Authorization"] = 'Basic <encoded-value>'
request.body = "{\n  \"name\": \"custom_segment_unique_name\",\n  \"attribute_name\": \"unique_identifier\",\n  \"attribute_type\": \"string\",\n  \"file_url\": \"https://s3.amazonaws.com/Sample_GAIDs.csv\",\n  \"callback_url\": \"http://example.com/moengage-callback\",\n  \"emails\": [\n    \"user1@example.com\",\n    \"user2@example.com\"\n  ],\n  \"expiry_time\": 30\n}"

response = http.request(request)
puts response.read_body

"No example response body available for this status code."

POST

custom-segments

file-segment

Create File Segment

curl --request POST \
  --url https://api-{dc}.moengage.com/v2/custom-segments/file-segment \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "custom_segment_unique_name",
  "attribute_name": "unique_identifier",
  "attribute_type": "string",
  "file_url": "https://s3.amazonaws.com/Sample_GAIDs.csv",
  "callback_url": "http://example.com/moengage-callback",
  "emails": [
    "user1@example.com",
    "user2@example.com"
  ],
  "expiry_time": 30
}
'

import requests

url = "https://api-{dc}.moengage.com/v2/custom-segments/file-segment"

payload = {
    "name": "custom_segment_unique_name",
    "attribute_name": "unique_identifier",
    "attribute_type": "string",
    "file_url": "https://s3.amazonaws.com/Sample_GAIDs.csv",
    "callback_url": "http://example.com/moengage-callback",
    "emails": ["user1@example.com", "user2@example.com"],
    "expiry_time": 30
}
headers = {
    "Content-Type": "<content-type>",
    "Authorization": "Basic <encoded-value>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': '<content-type>', Authorization: 'Basic <encoded-value>'},
  body: JSON.stringify({
    name: 'custom_segment_unique_name',
    attribute_name: 'unique_identifier',
    attribute_type: 'string',
    file_url: 'https://s3.amazonaws.com/Sample_GAIDs.csv',
    callback_url: 'http://example.com/moengage-callback',
    emails: ['user1@example.com', 'user2@example.com'],
    expiry_time: 30
  })
};

fetch('https://api-{dc}.moengage.com/v2/custom-segments/file-segment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-{dc}.moengage.com/v2/custom-segments/file-segment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'custom_segment_unique_name',
    'attribute_name' => 'unique_identifier',
    'attribute_type' => 'string',
    'file_url' => 'https://s3.amazonaws.com/Sample_GAIDs.csv',
    'callback_url' => 'http://example.com/moengage-callback',
    'emails' => [
        'user1@example.com',
        'user2@example.com'
    ],
    'expiry_time' => 30
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-{dc}.moengage.com/v2/custom-segments/file-segment"

	payload := strings.NewReader("{\n  \"name\": \"custom_segment_unique_name\",\n  \"attribute_name\": \"unique_identifier\",\n  \"attribute_type\": \"string\",\n  \"file_url\": \"https://s3.amazonaws.com/Sample_GAIDs.csv\",\n  \"callback_url\": \"http://example.com/moengage-callback\",\n  \"emails\": [\n    \"user1@example.com\",\n    \"user2@example.com\"\n  ],\n  \"expiry_time\": 30\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("Authorization", "Basic <encoded-value>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-{dc}.moengage.com/v2/custom-segments/file-segment")
  .header("Content-Type", "<content-type>")
  .header("Authorization", "Basic <encoded-value>")
  .body("{\n  \"name\": \"custom_segment_unique_name\",\n  \"attribute_name\": \"unique_identifier\",\n  \"attribute_type\": \"string\",\n  \"file_url\": \"https://s3.amazonaws.com/Sample_GAIDs.csv\",\n  \"callback_url\": \"http://example.com/moengage-callback\",\n  \"emails\": [\n    \"user1@example.com\",\n    \"user2@example.com\"\n  ],\n  \"expiry_time\": 30\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-{dc}.moengage.com/v2/custom-segments/file-segment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["Authorization"] = 'Basic <encoded-value>'
request.body = "{\n  \"name\": \"custom_segment_unique_name\",\n  \"attribute_name\": \"unique_identifier\",\n  \"attribute_type\": \"string\",\n  \"file_url\": \"https://s3.amazonaws.com/Sample_GAIDs.csv\",\n  \"callback_url\": \"http://example.com/moengage-callback\",\n  \"emails\": [\n    \"user1@example.com\",\n    \"user2@example.com\"\n  ],\n  \"expiry_time\": 30\n}"

response = http.request(request)
puts response.read_body

"No example response body available for this status code."

If your file is private, you should whitelist these IPs to provide access only to MoEngage for the file.

Check the data center and API endpoint mapping page here.

Limits

The limit of 1000 custom file segments is calculated only for the file segments that are active. Most of our customers utilize only 30-40% of this limit at any given point.

Rate Limit Name	Rate Limit
total active segment	The limit of the total number of active custom segments at a time for a client is 1000.
file_segment ops per hour	The total number of file segment operations (create/add/remove) per hour per client allowed is 10.
file_segment ops per day	The total number of file segment operations (create/add/remove) per day per client allowed is 100.
file_segment users per day	The total number of users uploaded via the File segment is limited to 2 million per day. (This limit is customizable, please get in touch with support)
file_size_limit	The size of the file from which the segment is created/updated. For each request, the file size limit is 150 MB.

Notes

Limits

Breaching the limits will reject the request.
Per hour and per day limits will consider the calculation based on the last hour and last 24 hrs respectively.

CSV File Requirements

The attribute names should be separated by new lines.
CSV should be a single column and less than 150MB.
Values should not end with a comma (e.g., abcd not abcd,).
Values should not have duplicates or special characters (e.g., abcd not "abcd" or a#bc).
File should not have empty rows or columns.
A user attribute value must uniquely identify a single user.
Sample File Link

Segment Processing & Availability

As soon as the request is received at the MoEngage system, MoEngage creates a custom segment with zero users. After this, the file is processed and users are added to the custom segment. If the created custom segment is queried in between the file processing, it will show zero or partial user count.

Authorizations

Authorization

string

header

required

Basic Authentication using your Workspace ID (as username) and Data API Key (as password) from the MoEngage Dashboard.

Headers

Content-Type

enum<string>

default:text/csv

required

Select the file content type.

Available options:

text/csv,

application/csv,

application/vnd.ms-excel,

text/plain,

application/octet-stream,

binary/octet-stream

Database

string

Set the database from which the data is available (MOE-DBNAME).

Body

application/json

Configuration for the new file segment.

Schema for creating a new file segment.

name

string

required

Name of the custom segment. Must be unique for creation.

attribute_name

string

required

Name of the user attribute to use as an identifier (e.g., 'ID', 'email').

attribute_type

enum<string>

required

The data type of the attribute_name.

Available options:

string,

double

file_url

string<uri>

required

A public, downloadable URL to a single-column CSV file.

expiry_time

integer<int32>

required

Segment expiry time in days. The segment is archived after this time.

callback_url

string<uri>

Callback URL to receive the result of segment processing.

emails

string<email>[]

List of email IDs to receive segment processing response.

Response

Everything worked as expected.

Getting Started

Endpoints

Create File Segment

Limits

Notes

Limits

CSV File Requirements

Segment Processing & Availability

Authorizations

Headers

Body

Response

​Limits

​Notes

​Limits

​CSV File Requirements

​Segment Processing & Availability

Authorizations

Headers

Body

Response

Limits

Notes

Limits

CSV File Requirements

Segment Processing & Availability