**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.
# Tutorial: Using Postman with the Amazon Pinpoint API
Postman is a popular tool for testing APIs in an easy-to-use graphical environment. You can use Postman to send API requests to any REST API, and to receive responses to your requests. Using Postman is a convenient way to test and troubleshoot the calls that you make to the Amazon Pinpoint API. This tutorial includes procedures for setting up and using Postman with Amazon Pinpoint.
**Note**
Postman is developed by a third-party company. It isn't developed or supported by Amazon Web Services (AWS). To learn more about using Postman, or for assistance with issues related to Postman, see the [Support center](https://support.postman.com/hc/en-us) on the Postman website.
## About this tutorial
This section contains an overview of this tutorial.
**Intended Audience**
This tutorial is intended for developers and system implementers. You don't have to be familiar with Amazon Pinpoint or Postman to complete the steps in this tutorial. You should be comfortable managing IAM policies and modifying JSON code examples.
The procedures in this tutorial were designed to prevent new users from using API operations that can permanently delete Amazon Pinpoint resources. Advanced users can remove this restriction by modifying the policy that's associated with their users.
**Features Used**
This tutorial includes usage examples for the following Amazon Pinpoint feature:
+ Interacting with the Amazon Pinpoint API by using Postman
**Time Required**
It should take about 15 minutes to complete this tutorial.
**Regional Restrictions**
There are no regional restrictions associated with using this solution.
**Resource Usage Costs**
There's no charge for creating an AWS account. However, by implementing this solution, you might incur AWS usage costs if you use Postman to do any of the following:
+ Send email, SMS, mobile push, or voice messages
+ Create and send campaigns
+ Use the phone number validation feature
For more information about the charges that are associated with using Amazon Pinpoint, see [Amazon Pinpoint pricing](https://aws.amazon.com/pinpoint/pricing/).
# Prerequisites for using Postman with Amazon Pinpoint
Before you begin this tutorial, complete the following prerequisites:
+ You must have an AWS account. To create an AWS account, go to [https://console.aws.amazon.com/](https://console.aws.amazon.com/) and choose **Create a new AWS account**.
+ Make sure that the account that you use to sign in to the AWS Management Console can create new IAM policies and roles.
+ Make sure you have at least one sample project created that has email turned on and a verified email identity. See [Creating an Amazon Pinpoint project with email support](https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-email-setup-create.html) in the *Amazon Pinpoint User Guide*.
+ Make sure you have an AWS Account ID. Your AWS Account ID can be found in the upper-right corner of the console or you can use the command line interface (CLI). See [Finding your AWS account ID](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-identifiers.html#FindAccountId).
+ You must download and install Postman on your computer. You can download Postman from the [Postman website](https://www.getpostman.com).
+ After you install Postman on your computer, create a Postman account. When you first start the Postman application, you're prompted to log in or create a new account. Follow the instructions provided by Postman to log in to your account or to create an account if you don't already have one.
**Next**: [Create IAM policies and roles](tutorials-using-postman-iam-user.md)
# Create IAM policies and roles for use with Amazon Pinpoint
When you use Postman to test the Amazon Pinpoint API, the first step is to create a user. In this section, you create a policy that permits users to interact with all the Amazon Pinpoint resources. Then, you create a user and attach the policy directly to the user .
## Create an IAM policy
Learn how to create an IAM policy. Users and roles that use this policy can interact with all of the resources in the Amazon Pinpoint API. It also provides access to resources that are associated with the Amazon Pinpoint Email API, as well as the Amazon Pinpoint SMS and Voice API.
**To create the policy**
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Policies**, and then choose **Create policy**.
1. In the **Policy editor** select **JSON**. Delete any JSON that is current in the **Policy editor** so that it is blank. Copy and paste the following JSON into the **Policy editor** and then in the **Policy editor** replace all instances of *123456789012* with your AWS account ID.
Your AWS account ID can be found in the upper right hand corner of the console, or you can use the CLI, see [Finding your AWS account ID](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-identifiers.html#FindAccountId).
**Note**
To protect the data in your Amazon Pinpoint account, this policy only includes permissions that allow you to read, create, and modify resources. It doesn't include permissions that allow you to delete resources. You can modify this policy by using the visual editor in the IAM console. For more information, see [Managing IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html) in the IAM User Guide. You can also use the [CreatePolicyVersion](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreatePolicyVersion.html) operation in the IAM API to update this policy.
Also, this policy includes permissions that permit you to interact with the `ses` and `sms-voice` services, in addition to the `mobiletargeting` service. The `ses` and `sms-voice` permissions allow you to interact with the Amazon Pinpoint Email API and Amazon Pinpoint SMS and Voice API, respectively. The `mobiletargeting` permissions allow you to interact with the Amazon Pinpoint API.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"mobiletargeting:Update*",
"mobiletargeting:Get*",
"mobiletargeting:Send*",
"mobiletargeting:Put*",
"mobiletargeting:Create*"
],
"Resource": [
"arn:aws:mobiletargeting:*:123456789012:apps/*",
"arn:aws:mobiletargeting:*:123456789012:apps/*/campaigns/*",
"arn:aws:mobiletargeting:*:123456789012:apps/*/segments/*"
]
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"mobiletargeting:TagResource",
"mobiletargeting:PhoneNumberValidate",
"mobiletargeting:ListTagsForResource",
"mobiletargeting:CreateApp"
],
"Resource": "arn:aws:mobiletargeting:*:123456789012:*"
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": [
"ses:TagResource",
"ses:Send*",
"ses:Create*",
"ses:Get*",
"ses:List*",
"ses:Put*",
"ses:Update*",
"sms-voice:SendVoiceMessage",
"sms-voice:List*",
"sms-voice:Create*",
"sms-voice:Get*",
"sms-voice:Update*"
],
"Resource": "*"
}
]
}
```
------
Choose **Next**.
1. For **Policy name**, enter a name for the policy, such as **PostmanAccessPolicy**. Choose **Create policy**.
1. (Optional) You can add tags to the policy by selecting **Add Tag**.
1. Choose **Next: Review**.
## Create an IAM user
**Warning**
IAM users have long-term credentials, which presents a security risk. To help mitigate this risk, we recommend that you provide these users with only the permissions they require to perform the task and that you remove these users when they are no longer needed.
After you create the policy, you can create a user and attach the policy to it. When you create the user, IAM provides a set of credentials that allow Postman to carry out Amazon Pinpoint API operations.
**To create the user**
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. On the IAM console, in the navigation pane, choose **Users**, and then choose **Create users**.
1. Under **User details**, for **User name**, enter a name that identifies the user, such as **PostmanUser**. Then choose **Next**.
1. Under **Set permissions**, for **Permissions options**, choose **Attach policies directly**.
1. Under **Permissions policies**, choose the policy (**PostmanAccessPolicy**) that you created in [Create an IAM policy](#tutorials-using-postman-iam-user-create-policy). Then choose **Next**.
1. On the **Review and create** page, optionally add tags that help you identify the user. For more information about using tags, see [Tagging IAM resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) in the *IAM User Guide*.
1. When you're ready to create the user, choose **Create user**.
## Create access keys
**Warning**
This scenario requires IAM users with programmatic access and long-term credentials, which presents a security risk. To help mitigate this risk, we recommend that you provide these users with only the permissions they require to perform the task and that you remove these users when they are no longer needed. Access keys can be updated if necessary. For more information, see [Update access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id-credentials-access-keys-update.html) in the *IAM User Guide*.
IAM provides a set of credentials that you can use to allow Postman to carry out Amazon Pinpoint API operations.
**To create the user**
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. On the IAM console, in the navigation pane, choose **Users**. Select the user (**PostmanUser**) created in [Create an IAM user](#tutorials-using-postman-iam-user-create-user), and then select the **Security credentials** tab.
1. In the **Access keys** section, choose **Create access key**.
1. On the **Access key best practices & alternatives** page, select **Application running outside AWS**.
Then choose **Next**.
1. (Optional) You can add a description tag to the policy.
1. Choose **Create access key**.
1. On the **Retrieve access keys** page, copy the credentials that are shown in the **Access key** and **Secret access key** columns.
**Note**
You must provide both the access key ID and the secret access key later in this tutorial. This is the only time that you're able to view the secret access key. We recommend that you copy it and save it in a safe location.
1. After you've saved both keys, choose **Done**.
**Next**: [Set up Postman](tutorials-using-postman-configuration.md)
# Set up Postman for use with Amazon Pinpoint
Now that you've created a user that's able to access the Amazon Pinpoint API, you can set up Postman. In this section, you create one or more environments in Postman. Next, you import a collection that contains a request template for each of the operations in the Amazon Pinpoint API.
## Create a Postman workspace
In Postman, a *workspace* is an organizational container for projects and environments. In this section, you create at least one workspace to use with Amazon Pinpoint.
**Create a workspace**
In Postman, choose the more actions choose **File**, then choose **New**.
1. On the **Create New** window, choose **Workspace**.
1. Enter a name, summary, and set the visibility to personal. Then choose **Create Workspace**.
## Create Postman environments
In Postman, an *environment* is a set of variables that are stored as key-value pairs. You can use environments to change the configuration of the requests that you make through Postman, without having to change the API requests themselves.
In this section, you create at least one environment to use with Amazon Pinpoint. Each environment that you create contains a set of variables that are specific to your account in a single AWS Region. If you use the procedures in this section to create more than one environment, you can change between Regions by choosing a different environment from the **Environment** menu in Postman.
**To create an environment**
1. In Postman, choose the more actions menu, choose **File**, then choose **New**.
1. On the **Create New** window, choose **Environment**.
1. On the **MANAGE ENVIRONMENTS** window, for **Environment Name**, enter **Amazon Pinpoint - *Region Name***. Replace *Region Name* with one of the following values:
+ US East (N. Virginia)
+ US West (Oregon)
+ Asia Pacific (Mumbai)
+ Asia Pacific (Sydney)
+ Europe (Frankfurt)
+ Europe (Ireland)
**Note**
At a minimum, you only need to create one environment for a single AWS Region, and that AWS Region must contain one project. If you haven't created a project in one of the previously listed AWS Regions, see [Creating an Amazon Pinpoint project with email support](https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-email-setup-create.html) in the *Amazon Pinpoint User Guide*.
1. Create six new variables: `endpoint`, `region`, `serviceName`, `accountId`, `accessKey`, and `secretAccessKey`. Use the following table to determine which value to enter in the **Initial Value** and **Current Value** columns for each variable.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pinpoint/latest/userguide/tutorials-using-postman-configuration.html)
After you create these variables, the **MANAGE ENVIRONMENTS** window resembles the example shown in the following image.
![\[\]](http://docs.aws.amazon.com/pinpoint/latest/userguide/images/Postman_Tutorial_2.1_4.png)
When you finish, choose **Save**.
**Important**
The access keys shown in the preceding image are fictitious. Don't share your IAM access keys with others.
Postman includes features that permit you to share and export environments. If you use these features, make sure not to share your access key ID and secret access key with anybody who shouldn't have access to these credentials.
For more information, see [IAM best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
1. (Optional) Repeat steps 1–4 for each additional environment that you want to create.
**Tip**
In Postman, you can create as many environments as you need. You can use environments in the following ways:
Create a separate environment for every Region where you must test the Amazon Pinpoint API.
Create environments that are associated with different AWS accounts.
Create environments that use credentials that are associated with other user.
1. When you finish creating environments, proceed to the next section.
## Create an Amazon Pinpoint collection in Postman
In Postman, a *collection* is a group of API requests. Requests in a collection are typically united by a common purpose. In this section, you create a new collection that contains a request template for each operation in the Amazon Pinpoint API.
**To create the Amazon Pinpoint collection**
1. In Postman, choose the more actions menu, choose **File**, then choose **Import**.
1. On the **Import** window, choose **Import From Link**, and then enter the following URL: [https://raw.githubusercontent.com/awsdocs/amazon-pinpoint-developer-guide/master/Amazon%20Pinpoint.postman\$1collection.json](https://raw.githubusercontent.com/awsdocs/amazon-pinpoint-developer-guide/master/Amazon%20Pinpoint.postman_collection.json).
Choose **Import**. Postman imports the Amazon Pinpoint collection, which contains 120 example requests.
## Test your Postman configuration
After you import the Amazon Pinpoint collection, we recommend that you perform a quick test to verify that all of the components are properly configured. You can test your configuration by submitting a `GetApps` request. This request returns a list of all of the projects that exist in your Amazon Pinpoint account in the current AWS Region. This request doesn't require any additional configuration, so it's a good way to test your configuration.
**To test the configuration of the Amazon Pinpoint collection**
1. In the left navigation pane, select **Collections**, expand the **Amazon Pinpoint** collection, and then expand the **Apps** folder.
1. In the list of requests, choose **GetApps**.
1. Use the **Environment** selector to choose the environment that you created in [Create Postman environments](#tutorials-using-postman-configuration-create-environments).
1. Choose **Send**. If the request is sent successfully, the response pane shows a status of `200 OK`. You see a response that resembles the example in the following image.
![\[\]](http://docs.aws.amazon.com/pinpoint/latest/userguide/images/Postman_Tutorial_2.3_3.png)
**Note**
If you don't have any projects created in the AWS Region then Amazon Pinpoint returns `{ "Item": [] }`.
This response shows a list of all of the Amazon Pinpoint projects that exist in your account in the Region that you chose in step 3.
### Troubleshooting
When you submit your request, you might see an error. See the following list for several common errors that you might encounter, and for steps that you can take to resolve them.
| Error message | Problem | Resolution |
| --- | --- | --- |
| Could not get any response There was an error connecting to https://%7B%7Bendpoint%7D%7D/v1/apps. | There is no current value for the `{{endpoint}}` variable, which is set when you choose an environment. | Use the environment selector to choose an environment. |
| The security token included in the request is invalid. | Postman wasn't able to find the current value of your access key ID or secret access key. | Choose the gear icon near the environment selector, and then choose the current environment. Verify that the `accessKey` and `secretAccessKey` values appear in both the **INITIAL VALUE** and **CURRENT VALUE** columns, and that you entered the credentials correctly. |
| "Message": "User: arn:aws:iam::123456789012:user/PinpointPostmanUser is not authorized to perform: mobiletargeting:GetApps on resource: arn:aws:mobiletargeting:us-west-2:123456789012:\$1" | The IAM policy associated with your user doesn't include the appropriate permissions. | Verify that your user has the permissions that are described in [Create an IAM policy](tutorials-using-postman-iam-user.md#tutorials-using-postman-iam-user-create-policy), and that you provided the correct credentials when you created the environment in [Create Postman workspace](#tutorials-using-postman-configuration-create-environments). |
**Next**: [Send additional requests](tutorials-using-postman-sample-requests.md)
# Send requests to the Amazon Pinpoint API
When you finish configuring and testing Postman, you can start sending additional requests to the Amazon Pinpoint API. This section includes information that you must know before you start sending requests. It also includes two sample requests that describe how to use the Amazon Pinpoint collection.
**Important**
When you complete the procedures in this section, you submit requests to the Amazon Pinpoint API. These requests create new resources in your Amazon Pinpoint account, modify existing resources, send messages, change the configuration of your Amazon Pinpoint projects, and use other Amazon Pinpoint features. Use caution when you carry out these requests.
## Examples in the Amazon Pinpoint Postman collection
You must configure most of the operations in the Amazon Pinpoint Postman collection before you can use them. For `GET` and `DELETE` operations, you typically only need to modify the variables that are set on the **Pre-request Script** tab.
**Note**
When you use the IAM policy that's shown in [Create an IAM policy](tutorials-using-postman-iam-user.md#tutorials-using-postman-iam-user-create-policy), you can't carry out any of the `DELETE` requests that are included in this collection.
For example, the `GetCampaign` operation requires you to specify a `projectId` and a `campaignId`. On the **Pre-request Script** tab, both of these variables are present, and are populated with example values. Delete the example values and replace them with the applicable values for your Amazon Pinpoint project and campaign.
Of these variables, the most commonly used is the `projectId` variable. The value for this variable should be the unique identifier for the project that your request applies to. To get a list of these identifiers for your projects, refer to the response to the `GetApps` request that you sent in the preceding step of this tutorial. In that response, the `Id` field provides the unique identifier for a project. To learn more about the `GetApps` operation and the meaning of each field in the response, see [Apps](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps.html) in the *Amazon Pinpoint API Reference*.
**Note**
In Amazon Pinpoint, a "project" is the same as an "app" or "application."
For `POST` and `PUT` operations, you must also modify the request body to include the values that you want to send to the API. For example, when you submit a `CreateApp` request, which is a `POST` request, you must specify a name for the project that you create. You can modify the request on the **Body** tab. In this example, replace the value next to `"Name"` with the name of the project. If you want to add tags to the project, you can specify them in the `tags` object. Or, if you don't want to add tags, you can delete the entire `tags` object.
**Note**
The `UntagResource` operation also requires you to specify URL parameters. You can specify these parameters on the **Params** tab. Replace the values in the **VALUE** column with the tags that you want to delete for the specified resource.
## Example request: Create a project by using the `CreateApp` operation
Before you create segments and campaigns in Amazon Pinpoint, you first have to create a project. In Amazon Pinpoint, a *project* consists of segments, campaigns, configurations, and data that are united by a common purpose. For example, you could use a project to contain all of the content that's related to a particular app, or to a specific brand or marketing initiative. When you add customer information to Amazon Pinpoint, that information is associated with a project.
**To create a project by sending a CreateApp API request**
1. On the **Environments** menu, choose the AWS Region that you want to create the project in.
![\[\]](http://docs.aws.amazon.com/pinpoint/latest/userguide/images/Postman_Tutorial_Environments.png)
In this example, Postman has been configured so that the **Environments** menu shows the following four options:
+ US East (N. Virginia)
+ US West (Oregon)
+ Europe (Frankfurt)
+ Europe (Ireland)
1. In the **Apps** folder, choose the **CreateApp** operation>.
![\[\]](http://docs.aws.amazon.com/pinpoint/latest/userguide/images/Postman_Tutorial_3.2_2.png)
The **Apps** folder in the Amazon Pinpoint Postman collection are expanded and show the following requests:
+ `GetApp`
+ `GetApps`
+ `CreateApp`
+ `DeleteApp`
1. On the **Body** tab, next to `"Name"`, replace the placeholder value (`"string"`) with a name for the campaign, such as **"MySampleProject"**.
1. Delete the comma after the campaign name, and then delete the entire `tags` object on lines 3 through 5. When you finish, your request should resemble the example that's shown in the following code snippet.
```
{
"Name": "MySampleProject"
}
```
Postman is configured to send the request as a raw JSON payload.
1. Choose **Send**. If the campaign is created successfully, the response pane shows a status of `201 Created`.
```
{
"Name": "MySampleProject"
"Id": "12345678901234567890123456789012",
"Arn": "arn:aws:mobiletargeting:us-east-1:123456789012:apps/12345678901234567890123456789012",
"tags": {}
}
```
## Example: Send an email by using the `SendMessages` operation
It's very common to use the Amazon Pinpoint `SendMessages` API to send transactional messages. One advantage to sending messages by using the `SendMessages` API as opposed to creating campaigns, is that you can send messages to any address, such as an email address, phone number, or device token. The address that you send messages to doesn't have to exist in your Amazon Pinpoint account. Let's compare this method to sending messages by creating campaigns. Before you send a campaign in Amazon Pinpoint, you must add endpoints to your Amazon Pinpoint account, create segments, create the campaign, and carry out the campaign.
The example in this section shows you how to send a transactional email message directly to a specific email address. You can modify this request to send messages through other channels, such as SMS, mobile push, or voice.
**To send an email message by submitting a SendMessages request**
1. Verify that the email channel is enabled for the project and the email address or domain that you want to use to send and receive the message is configured. For more information, see [Enabling and disabling the email channel](pinpoint/latest/userguide/channels-email-setup.html) and [Verifying email identities](https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-email-manage-verify.html) in the *Amazon Pinpoint User Guide*.
**Note**
To complete the procedure in this section, you must verify and email address
1. On the **Environments** menu, choose the AWS Region that you want to send the message from.
In this example, Postman has been configured so that the **Environments** menu shows the following four options:
+ US East (N. Virginia)
+ US West (Oregon)
+ Europe (Frankfurt)
+ Europe (Ireland)
1. In the **Messages** folder, choose the **SendMessages** operation.
![\[\]](http://docs.aws.amazon.com/pinpoint/latest/userguide/images/Postman_Tutorial_3.3_3.png)
1. On the **Pre-request Script** tab, replace the value of the `projectId` variable with the ID of a project that already exists in the Region that you selected in step 2 of this section.
1. On the **Body** tab, delete the example request that's shown in the request editor. Paste the following code:
```
{
"MessageConfiguration":{
"EmailMessage":{
"FromAddress":"sender@example.com",
"SimpleEmail":{
"Subject":{
"Data":"Sample Amazon Pinpoint message"
},
"HtmlPart":{
"Data":"Test message
This is a sample message sent from Amazon Pinpoint using the SendMessages API.
"
},
"TextPart":{
"Data":"This is a sample message sent from Amazon Pinpoint using the SendMessages API."
}
}
}
},
"Addresses":{
"recipient@example.com": {
"ChannelType": "EMAIL"
}
}
}
```
1. In the preceding code, replace *sender@example.com* with your verified email address. Replace *recipient@example.com* with the verified email address that you want to send the message to.
**Note**
If your account is still in the Amazon Pinpoint email sandbox, you can only send emails to addresses or domains that are verified in your Amazon Pinpoint account. For more information about having your account removed from the sandbox, see [ Requesting production access for email](https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-email-setup-production-access.html) in the *Amazon Pinpoint User Guide*.
1. Choose **Send**. If the message is sent successfully, the response pane shows a status of `200 OK`.
```
{
"ApplicationId": "12345678901234567890123456789012",
"RequestId": "",
"Result": {
"recipient@example.com": {
"DeliveryStatus": "SUCCESSFUL",
"StatusCode": 200,
"StatusMessage": "",
"MessageId": ""
}
}
}
```