Batch/newsletter recommendations

Batch recommendations allow you to request personalized content for thousands of users at once via a file-based interface. This is ideal for outbound channels like newsletters, or offline generation.

How it works

  1. Upload: You upload a CSV file containing user IDs and context to the Froomle SFTP server.

  2. Process: Froomle processes the file, generating recommendations for each row.

  3. Download: You retrieve a response CSV containing the recommended items for each user.

SFTP connection

Your account manager will provide credentials.

  • Host: {environment}@io.<subdomain>.froomle.com

  • Port: 2222 (not the default 22)

  • Auth: SSH2 RSA public key (shared in advance)

Request file format

File type: CSV (comma-separated). Each row represents one recommendation request (one user + context).

Required columns

  • environment

  • user_id or device_id (at least one)

  • list_name (must match a configured module)

  • list_size (number of items to return)

  • page_type (e.g. email, push)

Example request

environment,user_id,device_id,list_name,list_size,page_type
prod,user_123,,newsletter_daily,5,email
prod,user_456,,newsletter_daily,5,email

Response file format

File type: CSV. Each row represents one recommended item. If you requested 5 items for a user, you will get 5 rows for that user in the response.

Output columns

  • request_id: Unique ID for attribution (must be sent in tracking events).

  • list_name: The module name.

  • item_id: The recommended item.

  • rank: Rank of the item (1 = top recommendation).

  • user_group: Algorithm group attribution.

Example response

user_id,request_id,list_name,item_id,rank,user_group
user_123,req_abc,newsletter_daily,item_x,1,froomle
user_123,req_abc,newsletter_daily,item_y,2,froomle

Complex fields (JSON in CSV)

If you need to pass lists (like categories) in the request, you must escape them as a single CSV cell:

  1. Wrap the JSON array in double quotes.

  2. Escape internal quotes by doubling them.

Example:

"environment","list_name","categories"
"prod","mylist","[""news"",""sport""]"

Validation & Constraints

  • Duplicate definition: list_name should be unique per (user, device) pair in a single file.

  • Consistent Page Type: page_type must be identical for all rows in one file.

  • Deduplication: By default, items are deduplicated across multiple lists if you request them in the same batch.

Related topics