# Batch/newsletter recommendations

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/batch-requests.html)

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.

<a id="_how_it_works"></a>

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

<a id="_sftp_connection"></a>

## 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)
    

<a id="_request_file_format"></a>

## Request file format

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

<a id="_required_columns"></a>

### 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`)
    

<a id="_example_request"></a>

### Example request

```csv
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
```

<a id="_response_file_format"></a>

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

<a id="_output_columns"></a>

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

<a id="_example_response"></a>

### Example response

```csv
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
```

<a id="_complex_fields_json_in_csv"></a>

## 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**:

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

<a id="_validation_constraints"></a>

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

<a id="_related_topics"></a>

## Related topics

-   [Batch event contract](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/tracking-events.html#batch-open)
    
-   [Manual event integration](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/events.html)
    
-   [Manual real-time recommendation integration](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/recommendations.html)