> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon S3

> Sync custom events from Amazon S3 CSV files to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

export const PLATFORM_0 = "S3 CSV"

export const DATA_TYPE_0 = "file columns"

export const COLUMN_HEADER_0 = "CSV Column Example"

export const PROPERTIES_DESCRIPTION_0 = "Event properties as JSON string"

## Overview

The OneSignal + Amazon S3 integration enables automatic syncing of custom events from CSV files stored in your S3 bucket directly to OneSignal's Custom Events API. This allows you to trigger automated Journeys and personalized messaging campaigns based on real user behavior stored in your data warehouse.

You can sync events like purchases, product views, subscription changes, or any custom user actions to automatically trigger onboarding sequences, re-engagement campaigns, transactional messages, and targeted promotions across push notifications, email, in-app messages, and SMS.

***

## Requirements

### OneSignal

* **Custom Events** feature enabled

### Amazon S3

* **AWS Account** with S3 bucket access
* **IAM permissions** to create roles and policies
* **CSV files** with event data formatted according to OneSignal requirements
* **UTF-8 encoded** comma-delimited files with `.csv` extension

***

## Setup

### Prepare your event CSV files

Your S3 bucket must contain properly formatted CSV files with event data that OneSignal can process:

**File Format Requirements:**

* Uncompressed, UTF-8 encoded, comma delimited CSV with `.csv` file extension
* Include a header row (OneSignal will use headers as event field names)
* Represent null values with the string `#N/A`
* Values containing commas should be wrapped in double quotes
* Values containing double quotes should be escaped with a second double quote

**File Structure:**
OneSignal treats each **folder path as a unique data source** and considers the file name to be a version of the data within that path. When processing events, OneSignal will always select the newest data in the selected folder path based on timestamp.

When updating event data in S3, you can either replace the existing file or add a newer version. OneSignal will process the new events and send them to the Custom Events API.

### Create IAM role for OneSignal

OneSignal uses role-based authentication to connect to your S3 bucket, following AWS security best practices.

<Steps>
  <Step title="Create the IAM role">
    Create an IAM role in your AWS account that provides read-only access to your S3 bucket for OneSignal's AWS Account ID (`341876425553`):

    ```bash theme={null}
    aws iam create-role \
      --role-name OneSignalS3DataImport \
      --assume-role-policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
          "Action": "sts:AssumeRole"
        }]
      }'
    ```

    <Info>
      Save the returned Role ARN as you'll need it for the OneSignal configuration.
    </Info>
  </Step>

  <Step title="Grant S3 permissions">
    Grant your newly-created role read-only access to your S3 bucket:

    ```bash theme={null}
    aws iam put-role-policy \
      --role-name OneSignalS3DataImport \
      --policy-name OneSignalS3Access \
      --policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Action": [
            "s3:ListBucket",
            "s3:GetObject",
            "s3:GetObjectVersion",
            "s3:GetBucketLocation"
          ],
          "Resource": [
            "arn:aws:s3:::YOUR_BUCKET_NAME",
            "arn:aws:s3:::YOUR_BUCKET_NAME/*"
          ]
        }]
      }'
    ```

    <Warning>
      Replace `YOUR_BUCKET_NAME` with your actual S3 bucket name.
    </Warning>
  </Step>
</Steps>

### Configure OneSignal S3 connection

<Steps>
  <Step title="Navigate to Data Sources">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.
  </Step>

  <Step title="Select Amazon S3">
    Choose **Amazon S3** from the list of available integrations.
  </Step>

  <Step title="Enter connection details">
    Provide the following information:

    * **Region:** Your S3 bucket region
    * **Bucket Name:** Your S3 bucket name
    * **Role ARN:** The IAM role ARN from Step 1
    * **Prefix:** The folder path containing your event CSV files (optional)
  </Step>

  <Step title="Complete the security handshake">
    OneSignal will generate a unique external ID and display it on the next screen. Update your IAM role to require this external ID:

    ```bash theme={null}
    aws iam update-assume-role-policy \
      --role-name OneSignalS3DataImport \
      --policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
          "Action": "sts:AssumeRole",
          "Condition": {"StringEquals": {"sts:ExternalId": "GENERATED_EXTERNAL_ID"}}
        }]
      }'
    ```

    <Info>
      Replace `GENERATED_EXTERNAL_ID` with the external ID shown in the OneSignal dashboard.
    </Info>
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** in OneSignal to verify the setup is working correctly.
  </Step>
</Steps>

***

## CSV Processing Modes

OneSignal supports two modes when reading event CSV files from your S3 bucket:

### Most Recent (Default)

OneSignal processes only the most recent file in the configured S3 prefix and folder group. The single file is interpreted as the complete set of events to process. This mode works well when:

* A single file contains all events for a time period
* New versions of files are added over time with updated event data
* You want to process a complete batch of events at once

### Merge All

OneSignal takes every file in the configured S3 prefix and folder group and merges them into a single dataset before processing events. This mode is useful when:

* Your event data has been split into multiple files
* You want to process events from multiple sources
* Files are being added incrementally with new events

<Warning>
  In Merge All mode, all CSV files must have the exact same column names and order.
</Warning>

***

## Event Data Mapping

Once connected, you'll need to map your CSV columns to OneSignal custom event fields:

<Steps>
  <Step title="Review detected fields">
    OneSignal will automatically detect columns from your event CSV files and suggest mappings.
  </Step>

  <Step title="Map required event fields">
    Map the required fields for custom events:

    * **Event Name** (required): The name/type of the event
    * **External ID** (required): External User ID
    * **Event Timestamp** (optional): When the event occurred. Otherwise, assumed to be now.
  </Step>

  <Step title="Configure sync settings">
    Set your event processing frequency and delivery preferences.
  </Step>
</Steps>

***

### Event data mapping

Map your {PLATFORM_0} {DATA_TYPE_0} to OneSignal's custom events format:

| OneSignal Field | {COLUMN_HEADER_0} | Description                | Required |
| --------------- | ----------------- | -------------------------- | -------- |
| `name`          | `event_name`      | Event identifier           | Yes      |
| `external_id`   | `user_id`         | User identifier            | Yes      |
| `timestamp`     | `event_timestamp` | When event occurred        | No       |
| `properties`    | `event_data`      | {PROPERTIES_DESCRIPTION_0} | No       |

***

## Limitations

* **SQL Queries:** S3 sources do not support SQL queries or advanced transformations on event data
* **File Size:** Individual CSV files should not exceed 1GB
* **Update Frequency:** Minimum sync interval is 15 minutes
* **File Types:** Only CSV files are supported (no JSON, Parquet, etc.)

***

## FAQ

### What happens if my CSV file has formatting errors?

OneSignal will skip malformed rows and provide detailed error logs in the integrations dashboard. Common issues include missing required columns, invalid timestamp formats, and inconsistent column counts.

### How often does OneSignal check for new files?

OneSignal checks your S3 bucket based on your configured sync frequency, with a minimum interval of 15 minutes.

***

## Need help?

Contact our support team at `support@onesignal.com` or use the in-app chat for assistance with your S3 integration setup.