Overview

Auxiliary Data lets you import supplementary user information that is only relevant for a specific timeframe and does not need permanent storage, for example, limited-time offers and discounts, weekly contest points, or externally generated recommendations. You import it via file, use it to personalize campaigns for its lifetime, and let it expire automatically.

To enable Auxiliary Data for your account, contact your MoEngage Customer Success Manager (CSM) or the MoEngage Support team.

Auxiliary Data uses a materially different model from every other import type:

Primary-key mapping only: You select one column as the primary key. Every other column passes through automatically; there is no per-column mapping.
All values are stored as String: Auxiliary Data is force-typecast to the String datatype. Object, JSON, and Array types are not supported.
Configurable expiry: Each import has a retention period, after which the data expires.

Auxiliary Data is available for file-based sources only (S3, SFTP, and CSV). It is not available for data warehouse imports.

Use Cases

Auxiliary Data supports the following use cases:

Dynamic personalization: Upload coupon details, transaction data, survey data, or contest data to tailor communication.
Targeted engagement: Upload customer segments via file without storing them as permanent primary data.
Auto-refresh recurring campaigns: Periodically upload changing campaign content for automatic triggering.
Custom recommendations: Upload recommendations from in-house or external engines.
Legacy data integration: Ingest data from legacy platforms without complex integrations.

Supported Sources

Auxiliary Data can be imported via S3, SFTP, and CSV (manual upload). For file preparation, see Naming Conventions below.

Import Auxiliary Data

Entry point: Data > Data Imports > Import > Auxiliary Data. Select your source (S3, SFTP, or CSV) and click Continue.

MoEngage keeps historical logs of Auxiliary CSV files imported in the last 60 days. Files uploaded earlier no longer appear in the import logs, but their data is retained for the configured retention period.

Step 1: Configure Source and Format

Enter an Import name, then provide your source details:

S3
SFTP
CSV

Field	Description
S3 bucket name	The name of your S3 bucket.
S3 access key	The Access Key ID MoEngage uses to connect to your bucket.
S3 secret key	The Secret Access Key for that Access Key ID.
Region	The region your bucket is hosted in.
Folder Path	The path of the folder containing your files.

For more information, see Set Up a File Import.

Field	Description
Username	The username MoEngage uses to connect to your SFTP server.
Password	The password for that username.
Folder URL	The path of the folder containing your files.

For more information, see Set Up a File Import.

File encryption: For encrypted files, select Is your file encrypted? and provide your Decryption Key (private PGP key), Signing Key (public PGP key), and Key passphrase (used to encrypt your private key).

Set up PGP encryption

PGP (Pretty Good Privacy) lets you encrypt sensitive files before importing them. MoEngage supports PGP encryption for S3 and SFTP file imports.Prerequisites:

PGP key pair: A public key (to encrypt the file) and a private key (to decrypt it). Never share the private key.
Signing key pair: A public key (to sign the file, required for MoEngage SFTP integration) and a private key (used internally to verify the signature).

The following steps use GnuPG, a free implementation of the PGP standard.Step 1. Generate a key pair. Generate a PGP key pair using a tool such as GnuPG (gpg --full-generate-key), selecting RSA and a 1024-bit key size.

MoEngage supports file encryption using RSA keys of up to 1024 bits in length. Larger RSA keys, such as 4096-bit, are not supported and fail during decryption. Generate your key pair with a smaller RSA key size.
Turn off compression during encryption.

Step 2. Encrypt the file. Encrypt the file with your public key, then upload it to your S3 or SFTP folder. The --sign option signs the file while encrypting it.

gpg --encrypt --sign --armor --compress-algo none -r [email protected]

Step 3. Add the keys in the MoEngage UI. Enter your private key in the Decryption Key field and your passphrase in the Key Passphrase field during import setup.Step 4. Decrypt a file. Decryption requires your private key and its passphrase. In your PGP software, select the encrypted file and enter your passphrase to produce the unencrypted file. Python users can use the python-gnupg package:

import gnupg, os
gpg = gnupg.GPG(gnupghome=os.path.expanduser('~'))
gpg.encoding = 'utf-8'
import_result = gpg.import_keys(key_data)
gpg.trust_keys(import_result.fingerprints, "TRUST_ULTIMATE")
with open(encrypted_file_path, 'rb') as file:
    status = gpg.decrypt_file(file, passphrase="", output="/path/to/decrypted/file")
print(status.ok)

Step 5. Verify the file’s signature (optional). If you signed the file, add the public signing key on the MoEngage dashboard. MoEngage verifies the signature on the file in your S3 or SFTP folder. When verifying programmatically, a matched signature populates status.signature_id:

if status.signature_id:  # populated when the signature is verified, otherwise None
    print("signature verified")
else:
    print("not verified")

File name configuration: Specify the prefix and date-time format in your file name, separated by _. The prefix should use letters, numerals, and underscores. The default prefix is aux_data_, for example, aux_data_20220131.csv. Enter the prefix and time format, click Fetch Files, select a file to preview its top 5 rows, then click Next.

File names must follow the Naming Conventions.
Column names must not contain spaces.

Step 2: Map Your Data to MoEngage Attributes

Select the column that contains a unique value in each row as the Primary key from the dropdown. Every other column passes through automatically.

All Auxiliary Data is force-typecast to the String datatype.

MoEngage captures the column schema when you create the import, based on the selected file. Subsequent periodic runs ingest only these columns and do not re-read the file’s structure. Any column added to the file after the import is created is ignored. To use new columns, create a new Auxiliary Data import.

Optionally, turn on Send import status and select up to 10 email recipients. Click Next.

Step 3: Import Schedule and Frequency

Choose when and how often the import runs:

One Time: Run as soon as possible, or at a fixed timezone, start date, and send time.
Periodic: Run on a recurring schedule. Set the timezone, start date, and send time, then choose the periodicity:

Periodicity	Repeat rules
Hourly	Repeat every N hours.
Daily	Repeat every, the number of days between runs.
Weekly	Repeat every, the number of weeks between runs. Repeat on, the days of the week to run (for example, Monday, Wednesday, Friday).
Monthly	Repeat every, the number of months between runs. Repeat on, either Days of the month (specific dates; if a date doesn’t exist in a shorter month, the run falls on the last day) or Days of the week.

Data Action (Retention/Expiry)

Set the Aux data expiry, the retention period after which the data expires. Available values: 1, 2, 7, 15, 30 days, 2 months, 3 months, … up to 1 year, and Infinite retention.

One Time: Choose any retention period.
Periodic: Set the retention period longer than the import periodicity. For example, with a daily import and a 30-day retention, data imported on day 1 has 29 days of retention left when day 2’s data arrives.

Click Done to run the import. Editing the retention period: Edit an import’s retention period from its Actions (three-dot) menu > Edit, but only while (1) the data has not yet expired and (2) the periodic import has not yet run and processed in MoEngage.

Auxiliary Data is available for Email, SMS, Push, WhatsApp, In-App, Cards, Connectors, and Web Personalization.

Actions on an Auxiliary Data Import

From the Actions icon at the end of an import’s row:

View Details: See past imports, scheduled date and time, file name, status, and successful/failed upload counts.
Edit: Edit all fields except the import and segment names.
Duplicate: Duplicate the import.

File Preparation

Prepare your files to meet the following requirements:

File type: CSV. Column names must not contain spaces.
Naming: <prefix>_<date time format>.csv, default prefix aux_data_. For supported date-time formats, see Supported Datetime Formats.

Limits

Auxiliary Data imports have the following limits:

File size: Auxiliary Data follows the file-size limit of its source, less than 500 MB per file for S3/SFTP, and less than 150 MB per CSV for manual upload.
Rows: A single file supports up to your hourly row limit. Files exceeding your hourly row limit are rejected.

Rate limits: Auxiliary Data has its own independent rate-limit bucket:

Import Type	Hourly	Daily
Auxiliary Data	1.5M/hr	25M/day

Import Failure Policy

A failed run is retried automatically up to a maximum retry count. After the last retry, MoEngage marks the run FAILED, and it requires a manual re-trigger. The schedule itself continues independently, so a failed run does not block future scheduled runs.

Next Steps

After your import succeeds, use the data to personalize your campaigns:

Manage Your Imports

To monitor your imports, understand import statuses, or trigger a run manually or via API, see How Imports Work on the Imports Overview.

Frequently Asked Questions

My imports have failed. How do I check what went wrong?

Click the ellipsis on the right and click View to look up the Import details. Hover over the Failed Status to learn the reason.

What if a scheduled import adds the data into a recently archived segment?

In such cases, the new data will still be added to the archived segment. You can unarchive the segment as required.

Can an import be stopped while it's running?

Once an import process starts, it can’t be stopped midway. This is because the data goes through several steps, and interrupting it could lead to incomplete or inconsistent results. It’s best to let the current import finish.

How can I stop future runs of a scheduled import?

Yes, you can stop future scheduled imports from running automatically. To do this, find the import schedule and select the Archive option from the Actions menu on the Data Imports dashboard. This will prevent it from running on its next scheduled time.

What should I do if an import seems stuck or is taking a long time?

If an import appears to be stuck or is taking longer than usual, it’s best to wait. The system has checks in place to handle these situations automatically and retry if necessary. Manually starting the same import again while it’s still processing can cause conflicts and may prevent the original import from completing successfully.

​Overview

​Use Cases

​Supported Sources

​Import Auxiliary Data

​Step 1: Configure Source and Format

​Step 2: Map Your Data to MoEngage Attributes

​Step 3: Import Schedule and Frequency

​Data Action (Retention/Expiry)

​Actions on an Auxiliary Data Import

​File Preparation

​Limits

​Import Failure Policy

​Next Steps

​Manage Your Imports

​Frequently Asked Questions

Overview

Use Cases

Supported Sources

Import Auxiliary Data

Step 1: Configure Source and Format

Step 2: Map Your Data to MoEngage Attributes

Step 3: Import Schedule and Frequency

Data Action (Retention/Expiry)

Actions on an Auxiliary Data Import

File Preparation

Limits

Import Failure Policy

Next Steps

Manage Your Imports

Frequently Asked Questions