**End of support notice:** On October 30, 2026, AWS will end support for Amazon Pinpoint. After October 30, 2026, you will no longer be able to access the Amazon Pinpoint console or Amazon Pinpoint resources (endpoints, segments, campaigns, journeys, and analytics). For more information, see [Amazon Pinpoint end of support](https://docs.aws.amazon.com/console/pinpoint/migration-guide). **Note:** APIs related to SMS, voice, mobile push, OTP, and phone number validate are not impacted by this change and are supported by AWS End User Messaging. # IAM roles for common Amazon Pinpoint tasks An [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) is an AWS Identity and Access Management (IAM) identity that you can create in your AWS account and grant specific permissions. An IAM role is similar to an IAM user, in that it's an AWS identity with permissions policies that determine what the identity can and can't do in AWS. However, instead of being uniquely associated with one person, a role is intended to be assumable by anyone who needs it. Also, a role doesn't have standard long-term credentials such as a password or access keys associated with it. Instead, it provides temporary security credentials for a session. You can use IAM roles to delegate access to users, apps, applications, or services that don't normally have access to your AWS resources. For these reasons, you can use IAM roles to integrate Amazon Pinpoint with certain AWS services and resources for your account. For example, you might want to allow Amazon Pinpoint to access endpoint definitions that you store in an Amazon Simple Storage Service (Amazon S3) bucket and want to use for segments. Or you might want to allow Amazon Pinpoint to stream event data to an Amazon Kinesis stream for your account. Similarly, you might want to use IAM roles to allow web or mobile apps to register endpoints or report usage data for Amazon Pinpoint projects, without embedding AWS keys in the apps (where they can be difficult to rotate and users can potentially extract them). For these scenarios, you can delegate access to Amazon Pinpoint by using IAM roles. This section explains and provides examples of common Amazon Pinpoint tasks that use IAM roles to work with other AWS services. For information about using IAM roles with web and mobile apps, see [Providing access to externally authenticated users (identity federation)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html) in the *IAM User Guide*. **Topics** + [IAM role for importing endpoints or segments](permissions-import-segment.md) + [IAM role for exporting endpoints or segments](permissions-export-endpoints.md) + [Retrieving recommendations from Amazon Personalize](permissions-get-recommendations.md) + [IAM role for streaming events to Kinesis](permissions-streams.md) + [IAM role for streaming email events to Firehose](permissions-stream-email-events-kinesis.md) # IAM role for importing endpoints or segments With Amazon Pinpoint, you can define a user segment by importing endpoint definitions from an Amazon Simple Storage Service (Amazon S3) bucket in your AWS account. Before you import, you must delegate the required permissions to Amazon Pinpoint. To do this, you create an AWS Identity and Access Management (IAM) role and attach the following policies to the role: + The `AmazonS3ReadOnlyAccess` AWS managed policy. This policy is created and managed by AWS, and it grants read-only access to your Amazon S3 bucket. + A trust policy that allows Amazon Pinpoint to assume the role. After you create the role, you can use Amazon Pinpoint to import segments from an Amazon S3 bucket. For information about creating the bucket, creating endpoint files, and importing a segment by using the console, see [Importing segments](https://docs.aws.amazon.com/pinpoint/latest/userguide/segments-importing.html) in the *Amazon Pinpoint User Guide*. For an example of how to import a segment programmatically by using the AWS SDK for Java, see [Importing segments](https://docs.aws.amazon.com/pinpoint/latest/developerguide/segments-importing.html) in the *Amazon Pinpoint Developer Guide*. ## Attaching the trust policy To allow Amazon Pinpoint to assume the IAM role and perform the actions allowed by the `AmazonS3ReadOnlyAccess` policy, attach the following trust policy to the role: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowUserToImportEndpointDefinitions", "Effect": "Allow", "Principal": { "Service": "pinpoint.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ ## Creating the IAM role (AWS CLI) Complete the following steps to create the IAM role by using the AWS Command Line Interface (AWS CLI). If you haven't installed the AWS CLI, see [Install or update to the latest version of AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html) in the *AWS Command Line Interface User Guide*. **To create the IAM role by using the AWS CLI** 1. Create a JSON file that contains the trust policy for your role, and save the file locally. You can copy the trust policy provided in this topic. 1. At the command line, use the [https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) command to create the role and attach the trust policy: ``` aws iam create-role --role-name PinpointSegmentImport --assume-role-policy-document file://PinpointImportTrustPolicy.json ``` Following the `file://` prefix, specify the path to the JSON file that contains the trust policy. After you run this command, you will see an output that's similar to the following in your terminal: 1. Use the [https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html) command to attach the `AmazonS3ReadOnlyAccess` AWS managed policy to the role: ``` aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess --role-name PinpointSegmentImport ``` # IAM role for exporting endpoints or segments You can obtain a list of endpoints by creating an export job. When you create an export job, you must specify a project ID, and you can optionally specify a segment ID. Amazon Pinpoint then exports a list of the endpoints associated with the project or segment to an Amazon Simple Storage Service (Amazon S3) bucket. The resulting file contains a JSON-formatted list of endpoints and their attributes, such as channel, address, opt-in/opt-out status, creation date, and endpoint ID. To create an export job, you must configure an IAM role that allows Amazon Pinpoint to write to an Amazon S3 bucket. The process of configuring the role consists of two steps: 1. Create an IAM policy that allows an entity (in this case, Amazon Pinpoint) to write to a specific Amazon S3 bucket. 1. Create an IAM role and attach the policy to it. This topic contains procedures for completing both of these steps. These procedures assume that you've already created an Amazon S3 bucket, and a folder in that bucket, for storing exported segments. For information about creating buckets, see [Create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html) in the *Amazon Simple Storage Service User Guide*. These procedures also assume that you've already installed and configured the AWS Command Line Interface (AWS CLI). For information about setting up the AWS CLI, see [Get started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) in the *AWS Command Line Interface User Guide*. ## Step 1: Create the IAM policy An IAM policy defines the permissions for an entity, such as an identity or resource. To create a role for exporting Amazon Pinpoint endpoints, you must create a policy that grants permission to write to a specific folder in a specific Amazon S3 bucket. The following policy example follows the security practice of granting least privilege, meaning it grants only the permissions that are required to perform a single task. **To create the IAM policy** 1. In a text editor, create a new file. Paste the following code into the file: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowUserToSeeBucketListInTheConsole", "Action": [ "s3:ListAllMyBuckets", "s3:GetBucketLocation" ], "Effect": "Allow", "Resource": [ "arn:aws:s3:::*" ] }, { "Sid": "AllowRootAndHomeListingOfBucket", "Action": [ "s3:ListBucket" ], "Effect": "Allow", "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket-example-bucket" ], "Condition": { "StringEquals": { "s3:delimiter": [ "/" ], "s3:prefix": [ "", "Exports/" ] } } }, { "Sid": "AllowListingOfUserFolder", "Action": [ "s3:ListBucket" ], "Effect": "Allow", "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket-example-bucket" ], "Condition": { "StringLike": { "s3:prefix": [ "Exports/*" ] } } }, { "Sid": "AllowAllS3ActionsInUserFolder", "Action": [ "s3:*" ], "Effect": "Allow", "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket-example-bucket/Exports/*" ] } ] } ``` ------ In the preceding code, replace all instances of *amzn-s3-demo-bucket-example-bucket* with the name of the Amazon S3 bucket that contains the folder that you want to export the segment information into. Also, replace all instances of *Exports* with the name of the folder itself. When you finish, save the file as `s3policy.json`. 1. By using the AWS CLI, navigate to the directory where the `s3policy.json` file is located. Then enter the following command to create the policy: ``` aws iam create-policy --policy-name s3ExportPolicy --policy-document file://s3policy.json ``` If the policy was created successfully, you will see an output similar to the following: ``` { "Policy": { "CreateDate": "2018-04-11T18:44:34.805Z", "IsAttachable": true, "DefaultVersionId": "v1", "AttachmentCount": 0, "PolicyId": "ANPAJ2YJQRJCG3EXAMPLE", "UpdateDate": "2018-04-11T18:44:34.805Z", "Arn": "arn:aws:iam::123456789012:policy/s3ExportPolicy", "PolicyName": "s3ExportPolicy", "Path": "/" } } ``` Copy the Amazon Resource Name (ARN) of the policy (`arn:aws:iam::123456789012:policy/s3ExportPolicy` in the preceding example). In the next section, you must supply this ARN when you create the role. **Note** If you receive a message stating that your account isn't authorized to perform the `CreatePolicy` operation, then you must attach a policy to your user account that lets you create new IAM policies and roles. For more information, see [Adding and removing IAM identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#attach-managed-policy-console) in the *IAM User Guide*. ## Step 2: Create the IAM role Now that you've created an IAM policy, you can create a role and attach the policy to it. Each IAM role contains a *trust policy*—a set of rules that specifies which entities are allowed to assume the role. In this section, you create a trust policy that allows Amazon Pinpoint to assume the role. Next, you create the role itself, and then attach the policy that you created in the previous section. **To create the IAM role** 1. In a text editor, create a new file. Paste the following code into the file: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":"pinpoint.amazonaws.com" }, "Action":"sts:AssumeRole" } ] } ``` ------ Save the file as `trustpolicy.json`. 1. By using the AWS CLI, navigate to the directory where the `trustpolicy.json` file is located. Then enter the following command to create a new role: ``` aws iam create-role --role-name s3ExportRole --assume-role-policy-document file://trustpolicy.json ``` If the command runs successfully, you will see an output similar to the following: 1. At the command line, enter the following command to attach the policy that you created in the previous section to the role that you created: ``` aws iam attach-role-policy --policy-arn arn:aws:iam::123456789012:policy/s3ExportPolicy --role-name s3ExportRole ``` In the preceding command, replace *arn:aws:iam::123456789012:policy/s3ExportPolicy* with the ARN of the policy that you created in the previous section. # Retrieving recommendations from Amazon Personalize You can configure Amazon Pinpoint to retrieve recommendation data from an Amazon Personalize solution that's been deployed as an Amazon Personalize campaign. You can use this data to send personalized recommendations to message recipients based on each recipient's attributes and behavior. To learn more, see [Machine learning models](https://docs.aws.amazon.com/pinpoint/latest/userguide/ml-models.html) in the *Amazon Pinpoint User Guide*. Before you can retrieve recommendation data from an Amazon Personalize campaign, you must create an AWS Identity and Access Management (IAM) role that allows Amazon Pinpoint to retrieve the data from the campaign. Amazon Pinpoint can create this role for you automatically when you use the console to set up a recommender model in Amazon Pinpoint. Or, you can create this role manually. To create the role manually, use the IAM API to complete the following steps: 1. Create an IAM policy that allows an entity (in this case, Amazon Pinpoint) to retrieve recommendation data from an Amazon Personalize campaign. 1. Create an IAM role and attach the IAM policy to it. This topic explains how to complete these steps by using the AWS Command Line Interface (AWS CLI). It assumes that you've already created the Amazon Personalize solution and deployed it as an Amazon Personalize campaign. For information about creating and deploying a campaign, see [Creating a campaign](https://docs.aws.amazon.com//personalize/latest/dg/campaigns.html#create-campaign-cli) in the *Amazon Personalize Developer Guide*. This topic also assumes that you've already installed and configured the AWS CLI. For information about setting up the AWS CLI, see [Get started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) in the *AWS Command Line Interface User Guide*. ## Step 1: Create the IAM policy An IAM policy defines permissions for an entity, such as an identity or resource. To create a role that allows Amazon Pinpoint to retrieve recommendation data from an Amazon Personalize campaign, you must first create an IAM policy for the role. This policy must allow Amazon Pinpoint to do the following: + Retrieve configuration information for the solution that's deployed by the campaign (`DescribeSolution`). + Check the status of the campaign (`DescribeCampaign`). + Retrieve recommendation data from the campaign (`GetRecommendations`). In the following procedure, the example policy allows this access for a particular Amazon Personalize solution that was deployed by a particular Amazon Personalize campaign. **To create the IAM policy** 1. In a text editor, create a new file. Paste the following code into the file: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "RetrieveRecommendationsOneCampaign", "Effect": "Allow", "Action": [ "personalize:DescribeSolution", "personalize:DescribeCampaign", "personalize:GetRecommendations" ], "Resource": [ "arn:aws:personalize:us-east-1:111122223333:solution/solutionId", "arn:aws:personalize:us-east-1:111122223333:campaign/campaignId" ] } ] } ``` ------ In the preceding example, replace the *italicized* text with your information: + *region* – The name of the AWS Region that hosts the Amazon Personalize solution and campaign. + *accountId* – Your AWS account ID. + *solutionId* – The unique resource ID for the Amazon Personalize solution that's deployed by the campaign. + *campaignId* – The unique resource ID for the Amazon Personalize campaign from which to retrieve recommendation data. 1. When you finish, save the file as `RetrieveRecommendationsPolicy.json`. 1. By using the command line interface, navigate to the directory where you saved the `RetrieveRecommendationsPolicy.json` file. 1. Enter the following command to create a policy and name it `RetrieveRecommendationsPolicy`. To use a different name, change *RetrieveRecommendationsPolicy* to the name that you want. ``` aws iam create-policy --policy-name RetrieveRecommendationsPolicy --policy-document file://RetrieveRecommendationsPolicy.json ``` If the policy was created successfully, you will see an output similar to the following: ``` { "Policy": { "PolicyName": "RetrieveRecommendationsPolicy", "PolicyId": "ANPAJ2YJQRJCG3EXAMPLE", "Arn": "arn:aws:iam::123456789012:policy/RetrieveRecommendationsPolicy", "Path": "/", "DefaultVersionId": "v1", "AttachmentCount": 0, "PermissionBoundaryUsageCount": 0, "IsAttachable": true, "CreateDate": "2020-03-04T22:23:15Z", "UpdateDate": "2020-03-04T22:23:15Z" } } ``` **Note** If you receive a message that your account isn't authorized to perform the `CreatePolicy` operation, you must attach a policy to your user account that lets you create new IAM policies and roles for your account. For more information, see [Adding and removing IAM identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#attach-managed-policy-console) in the *IAM User Guide*. 1. Copy the Amazon Resource Name (ARN) of the policy (`arn:aws:iam::123456789012:policy/RetrieveRecommendationsPolicy` in the preceding example). You need this ARN to create the IAM role in the next section. ## Step 2: Create the IAM role After you create the IAM policy, you can create an IAM role and attach the policy to it. Each IAM role contains a *trust policy*, which is a set of rules that specifies which entities are allowed to assume the role. In this section, you create a trust policy that allows Amazon Pinpoint to assume the role. Next, you create the role itself. Then, you attach the policy to the role. **To create the IAM role** 1. In a text editor, create a new file. Paste the following code into the file: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect": "Allow", "Principal": { "Service": "pinpoint.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ 1. Save the file as `RecommendationsTrustPolicy.json`. 1. By using the command line interface, navigate to the directory where you saved the `RecommendationsTrustPolicy.json` file. 1. Enter the following command to create a new role and name it `PinpointRoleforPersonalize`. To use a different name, change *PinpointRoleforPersonalize* to the name that you want. ``` aws iam create-role --role-name PinpointRoleforPersonalize --assume-role-policy-document file://RecommendationsTrustPolicy.json ``` If the command runs successfully, you will see an output similar to the following: ``` ``` 1. Enter the following command to attach the policy that you created in the previous section to the role that you created: ``` aws iam attach-role-policy --policy-arn arn:aws:iam::123456789012:policy/RetrieveRecommendationsPolicy --role-name PinpointRoleforPersonalize ``` In the preceding command, replace *arn:aws:iam::123456789012:policy/RetrieveRecommendationsPolicy* with the ARN of the policy that you created in the previous section. Also, replace *PinpointRoleforPersonalize* with the name of the role that you specified in step 4, if you specified a different name for the role. # IAM role for streaming events to Kinesis Amazon Pinpoint can automatically send *app usage data*, or *event data*, from your app to an Amazon Kinesis data stream or Amazon Data Firehose delivery stream in your AWS account. Before Amazon Pinpoint can begin streaming the event data, you must delegate the required permissions to Amazon Pinpoint. If you use the console to set up event streaming, Amazon Pinpoint will automatically create an AWS Identity and Access Management (IAM) role with the required permissions. For more information, see [Streaming Amazon Pinpoint events to Kinesis](https://docs.aws.amazon.com/pinpoint/latest/userguide/analytics-streaming-kinesis.html) in the *Amazon Pinpoint User Guide*. If you want to create the role manually, attach the following policies to the role: + A permissions policy that allows Amazon Pinpoint to send event data to your stream. + A trust policy that allows Amazon Pinpoint to assume the role. After you create the role, you can configure Amazon Pinpoint to send events to your stream automatically. For more information, see [Streaming Amazon Pinpoint events to Kinesis](https://docs.aws.amazon.com/pinpoint/latest/developerguide/event-streams.html) in the *Amazon Pinpoint Developer Guide*. ## Permissions policies To allow Amazon Pinpoint to send event data to your stream, attach one of the following policies to the role. ### Amazon Kinesis Data Streams The following policy allows Amazon Pinpoint to send event data to a Kinesis stream. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Action": [ "kinesis:PutRecords", "kinesis:DescribeStream" ], "Effect": "Allow", "Resource": [ "arn:aws:kinesis:us-east-1:111122223333:stream/stream-name" ] } } ``` ------ ### Amazon Data Firehose The following policy allows Amazon Pinpoint to send event data to a Firehose delivery stream. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "firehose:PutRecordBatch", "firehose:DescribeDeliveryStream" ], "Resource": [ "arn:aws:firehose:us-east-1:111122223333:deliverystream/delivery-stream-name" ] } } ``` ------ ## Trust policy To allow Amazon Pinpoint to assume the IAM role and perform the actions allowed by the permissions policy, attach the following trust policy to the role: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "pinpoint.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ ## Creating the IAM role (AWS CLI) Complete the following steps to create the IAM role by using the AWS Command Line Interface (AWS CLI). To learn how to create the role by using the Amazon Pinpoint console, see [Streaming Amazon Pinpoint events to Kinesis](https://docs.aws.amazon.com/pinpoint/latest/userguide/analytics-streaming-kinesis.html#analytics-streaming-kinesis-setup) in the *Amazon Pinpoint User Guide*. If you haven't installed the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html) in the *AWS Command Line Interface User Guide*. **To create the IAM role by using the AWS CLI** 1. Create a JSON file that contains the trust policy for your role, and save the file locally. You can copy the trust policy provided in this topic. 1. Use the [https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) command to create the role and attach the trust policy: ``` aws iam create-role --role-name PinpointEventStreamRole --assume-role-policy-document file://PinpointEventStreamTrustPolicy.json ``` Following the `file://` prefix, specify the path to the JSON file that contains the trust policy. After you run this command, the AWS CLI prints the following output in your terminal: 1. Create a JSON file that contains the permissions policy for your role, and save the file locally. You can copy one of the policies provided in the [Permissions policies](#permissions-streams-permissionspolicies) section of this topic. 1. Use the [https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-policy.html](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-policy.html) command to attach the permissions policy to the role: ``` aws iam put-role-policy --role-name PinpointEventStreamRole --policy-name PinpointEventStreamPermissionsPolicy --policy-document file://PinpointEventStreamPermissionsPolicy.json ``` Following the `file://` prefix, specify the path to the JSON file that contains the permissions policy. # IAM role for streaming email events to Firehose In the Amazon Pinpoint Email API, you can create *configuration sets* that specify how to handle certain email events. For example, you can create a configuration set that sends delivery notifications to a specific *event destination*, such as an Amazon SNS topic or an Amazon Data Firehose delivery stream. When you send email through the Amazon Pinpoint Email API using that configuration set, Amazon Pinpoint sends information about email-related events to the event destination that you specified in the configuration set. The Amazon Pinpoint Email API can deliver information about the following types of email events to the event destinations that you specify: + **Sends** – The call to Amazon Pinpoint was successful, and Amazon Pinpoint attempted to deliver the email. + **Deliveries** – Amazon Pinpoint successfully delivered the email to the recipient's mail server. + **Rejections** – Amazon Pinpoint accepted the email, determined that it contained malware, and rejected it. Amazon Pinpoint didn't attempt to deliver the email to the recipient's mail server. + **Rendering Failures** – The email wasn't sent because of a template rendering issue. This event type only occurs when you send an email that includes substitution tags. This event type can occur when substitution values are missing. It can also occur when there's a mismatch between the substitution tags that you used in the email and the substitution data that you provided. **Note** If you use substitution tags in the emails that you send by using the Amazon Pinpoint Email API, you should always create a configuration set that records Rendering Failure events. + **Bounces** – The recipient's mail server permanently rejected the email. + **Complaints** – The email was successfully delivered to the recipient, but the recipient used the "Report Spam" (or equivalent) feature of their email client to report the message. + **Opens** – The recipient received the message and opened it in their email client. + **Clicks** – The recipient clicked one or more links that were contained in the email. **Note** Every time a recipient opens or clicks an email, Amazon Pinpoint generates unique open or click events, respectively. In other words, if a specific recipient opens a message five times, Amazon Pinpoint reports five separate Open events. If you want to send data about these events to a Firehose stream, you must create an IAM role that has the appropriate permissions. The role must use the following policies: + A trust policy that allows Amazon Pinpoint to assume the role. + A permissions policy that allows the Amazon Pinpoint Email API to send email delivery and response records to your stream. After you create the role, you can configure Amazon Pinpoint to send events to your stream automatically. For more information, see [Streaming Amazon Pinpoint events to Kinesis](https://docs.aws.amazon.com/pinpoint/latest/developerguide/event-streams.html) in the *Amazon Pinpoint Developer Guide*. ## Trust policy To allow the Amazon Pinpoint Email API to assume the IAM role and perform the actions allowed by the permissions policy, attach the following trust policy to the role: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "ses.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "accountId" } } } ] } ``` ------ In the preceding example, replace *accountId* with the ID of your AWS account. ## Permissions policy To allow the Amazon Pinpoint Email API to send email event data to a Firehose delivery stream, attach the following permissions policy to a role. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "firehose:PutRecordBatch", "firehose:DescribeDeliveryStream" ], "Resource": [ "arn:aws:firehose:us-east-1:111122223333:deliverystream/deliveryStreamName" ] } } ``` ------ In the preceding example, replace *region* with the name of the AWS Region in which you created the delivery stream. Replace *accountId* with the ID of your AWS account. Finally, replace *deliveryStreamName* with the name of the delivery stream. ## Creating the IAM role (AWS CLI) Complete the following steps to create the IAM role by using the AWS Command Line Interface (AWS CLI). For information about installing and configuring the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html) in the *AWS Command Line Interface User Guide*. **To create the IAM role by using the AWS CLI** 1. Create a JSON file that contains the trust policy for your role, and then save the file locally. You can copy the [trust policy](#permissions-stream-email-events-kinesis-trustpolicy) that's provided earlier in this topic. 1. Use the [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) command to create the role and attach the trust policy: ``` aws iam create-role --role-name PinpointEventStreamRole \ --assume-role-policy-document file://PinpointEventStreamTrustPolicy.json ``` In the preceding example, replace *PinpointEventStreamTrustPolicy.json* with the full path to the file that contains the trust policy. After you run this command, the AWS CLI returns the following output: 1. Create a JSON file that contains the permissions policy for your role, and then save the file locally. You can copy the [permissions policy](#permissions-stream-email-events-kinesis-permissionspolicies) that's provided earlier in this topic. 1. Use the [put-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-policy.html) command to attach the permissions policy to the role: ``` aws iam put-role-policy \ --role-name PinpointEventStreamRole \ --policy-name PinpointEventStreamPermissionsPolicy --policy-document file://PinpointEventStreamPermissionsPolicy.json ``` In the preceding example, replace *PinpointEventStreamPermissionsPolicy.json* with the full path to the file that contains the permissions policy.