Setting up Stored Messages for AWS S3

Iterable's Stored Messages feature can archive sent messages for email, SMS, and push in your AWS S3 bucket. Follow this guide to get started with Stored Messages by connecting your AWS S3 bucket to Iterable.

# In this article

# Setup overview

To connect Stored Messages to your AWS S3 bucket, follow these steps:

1. In Iterable, a user with the Manage Integrations permission can get the required IAM policy details. Provide them to your AWS administrator.
2. In AWS, create an IAM role with specific configurations:
   • Set a role name with the required prefix (iterable-stored-messages).
   • Set the trust policy of this role.
   • (optional) Add permissions for KMS encryption if you've enabled KMS encryption for the S3 bucket.
   • Ensure the role’s identity policy allows writing objects to S3 from your specified region.
3. Get the values for Role ARN, Role Session Name, Region, and S3 Bucket Name, and give them to an Iterable administrator or user with the Manage Integrations permission.
4. In Iterable, add your AWS storage bucket as the destination for Stored Messages in your Iterable project.

Continue reading this article for more details on each step of the setup process.

# AWS security measures and recommendations

# AWS policies

Iterable uses a wildcard allowance policy for its IAM policy. Your trust policy should allow the Iterable IAM role and configure an ExternalId, including necessary permissions for AssumeRole and S3-specific actions like ListBucket (implicitly from the broader policy Iterable might use) and PutObject.

# Bucket ownership verification

Iterable verifies bucket ownership when writing to S3 by using the bucket owner condition. The AWS account ID, retrievable from the Role ARN, is used to validate that you own the S3 bucket, ensuring that users can only write to S3 buckets they own.

# Data encryption

While data is in transit, all data transfer happens over HTTPS (TLS):

• By default, Iterable uses an AWS S3 SDK that has SSL enabled.
• Iterable enforces aws:SecureTransport on all S3 writes and sts:AssumeRole calls. This ensures that data is transferred over a secure connection.

Iterable doesn't handle encryption during storage—your organization owns the bucket and is responsible for configuring encryption while data is at rest. You can enable S3 Server-side encryption or Customer Managed Key (CMK) via KMS encryption for your bucket.

# Data access

The storage bucket should be private. Stored messages can contain sensitive PII including email addresses, phone numbers, and message contents.

When you set up Stored Messages, Iterable requires a simple checkbox confirmation that you've configured your bucket to be private. This is to prevent exposure of customer data, including sensitive personally identifiable information (PII).

# Step 1: Get required IAM policy details from Iterable

An Iterable user with the Manage Integrations permission can get the required IAM policy details from Iterable.

1. Go to Integrations > Stored Messages
2. Click Connect a Destination
3. Select S3
4. Click Continue
5. Copy these values and provide them to your AWS administrator:
   • External Org ID: The unique identifier generated by Iterable for your organization.
     • This adds security to prevent the confused deputy problem
   • Iterable Role ARN: The AWS Role ARN Iterable assumes when writing to S3.
     • This value is used as the Principal in the trust policy.
   • IAM Role Prefix: The prefix of the IAM role Iterable assumes when writing to S3.
     • This value must be used as a prefix for the IAM role name you create.

Next, your AWS administrator can create an IAM role and policies with the provided details.

# Step 2: Set up an IAM role and policies in AWS

Ask your AWS administrator to create an IAM policy and role for Iterable to use when writing to S3:

1. Create an IAM role. The new role's name must begin with the IAM Role Prefix value (iterable-stored-messages) and you can append more text to make it unique. It's important that the role name conforms to the prefix format iterable-stored-messages, as Iterable’s security policy allows assuming only roles following this naming convention.

   Some example IAM role names:

   • iterable-stored-messages
   • iterable-stored-messages-fiterable-inc
   • iterable-stored-messages-fiterable-eu-12345

2. Set the trust policy of this role. The trust policy allows the Iterable IAM role to assume the role you created.

   Use the following JSON block as a template for the trust policy.

   • Replace <iterable-role-arn> with the Iterable Role ARN obtained in step 1.
   • Replace <external-org-id> with the External Org ID obtained in step 1.

   {
     "Version": "2012-10-17",
     "Statement": {
       "Effect": "Allow",
       "Principal": {
         "AWS": "<iterable-role-arn>"
       },
       "Action": "sts:AssumeRole",
       "Condition": {
         "StringEquals": {
           "sts:ExternalId": "<external-org-id>"
         }
       }
     }
   }
   

3. (optional) Add permissions for KMS encryption. If you’ve enabled KMS encryption for the S3 bucket, add a statement like the following to the role's identity policy:

   {
     "Effect": "Allow",
     "Action": [
       "kms:Encrypt",
       "kms:Decrypt",
       "kms:GenerateDataKey*"
     ],
     "Resource": "<kms-key-arn>"
   }
   

   • kms:Encrypt is included here as part of a broader example policy for KMS-encrypted writes. Depending on your configuration, AWS may not require it for every upload path.
   • kms:Decrypt is required if the upload path uses multipart upload.
   • kms:GenerateDataKey* is required for SSE-KMS uploads.
   • Replace <kms-key-arn> with the ARN of the KMS key used to encrypt your S3 bucket.

4. Ensure the role’s identity policy allows writing objects to S3 from your specified region. This policy grants the necessary S3 permissions.

   Use the following JSON block as a template for the identity policy.

   • Replace <bucket-name> with the name of your S3 bucket (such as your-bucket-name).
   • The s3:PutObject action is essential for Iterable to store messages.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:PutObject"
         ],
         "Resource": "arn:aws:s3:::<bucket-name>/*"
       }
     ]
   }
   

# Next steps

Once the role is ready, get the values for Role ARN, Role Session Name, Region, and S3 Bucket Name, and give them to an Iterable user with the Manage Integrations permission. They can follow the setup guide for Iterable next. Once they connect your AWS S3 bucket to Stored Messages, Iterable starts archiving sent messages for email, SMS, and push in your AWS S3 bucket.

To view archived messages, access the data in your S3 bucket directly or use a third-party tool to access the data. To learn about the file naming conventions and JSON payload structures as stored in your S3 bucket, see Stored Message JSON Payloads.