Error message Problem Resolution
Make sure that the accessKey and secretAccessKey values appear in both the INITIAL VALUE and CURRENT VALUE columns, and that you entered the credentials correctly.
The IAM policy associated with your user doesn't include the appropriate permissions.
Make sure that your IAM user has the permissions that are described in Step 1.1 (p. 4), and that you provided the correct credentials when you created the environment in Step 2.1 (p. 6).
Step 3: Send additional requests
When you finish configuring and testing Postman, you can start sending additional requests to the Amazon Pinpoint API. This section includes information that you need to know before you start sending requests. It also includes two sample requests that help you understand 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 are capable of creating new resources in your Amazon Pinpoint account, modifying existing resources, sending messages, changing the configuration of your Amazon Pinpoint projects, and using other Amazon Pinpoint features. Use caution when you execute these requests.
About the examples in the Amazon Pinpoint Postman collection
You have to 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 Step 1.1 (p. 4), you can't execute 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 appropriate 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, you can refer to the response to the GetApps request that you sent in the preceding step of this tutorial. (In Amazon Pinpoint, a "project" is the same thing as an "app" or
"application.") 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 in the Amazon Pinpoint API Reference.
For POST and PUT operations, you also need to 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),
Step 3: Send additional requests
you have to 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.
NoteThe 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: Creating 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, as shown in the following image.
2. In the Apps folder, choose the CreateApp operation, as shown in the following image.
Step 3: Send additional requests
3. On the Body tab, next to "Name", replace the placeholder value ("string") with a name for the campaign, such as "MySampleProject".
4. Delete the comma that 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 image.
5. Choose Send. If the campaign is created successfully, the response pane shows a status of 201 Created. You see a response that resembles the example in the following image.
Example: Sending 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 use the SendMessages API to 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 already. Compare this to sending messages by creating campaigns. Before
Step 3: Send additional requests
you send a campaign in Amazon Pinpoint, you have to add endpoints to your Amazon Pinpoint account, create segments, create the campaign, and execute 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 the email address or domain that you want to use to send the message. For more information, see Verifying email identities in the Amazon Pinpoint User Guide.
NoteIn Amazon Pinpoint, you can only send email from addresses or domains that you've verified. You won't be able to complete the procedure in this section until you verify an email address.
2. On the Environments menu, choose the AWS Region that you want to send the message from, as shown in the following image.
3. In the Messages folder, choose the SendMessages operation.
Step 3: Send additional requests
4. 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.
5. On the Body tab, delete the example request that's shown in the request editor. Paste the following code:
{
"MessageConfiguration":{
"EmailMessage":{
"FromAddress":"[email protected]", "SimpleEmail":{
"Subject":{
"Data":"Sample Amazon Pinpoint message"
},
"HtmlPart":{
"Data":"<h1>Test message</h1><p>This is a sample message sent from <a href=\"https://aws.amazon.com/pinpoint\">Amazon Pinpoint</a> using the SendMessages API.</p>"
},
"TextPart":{
"Data":"This is a sample message sent from Amazon Pinpoint using the SendMessages API."
}
Setting up an SMS registration system
} } },
"Addresses":{
"[email protected]": { "ChannelType": "EMAIL"
} } }
6. In the preceding code, replace [email protected] with your verified email address. Replace [email protected] with the address that you want to send the message to.
NoteIf your account is still in the Amazon Pinpoint email sandbox, you can only send email 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 in the Amazon Pinpoint User Guide.
7. Choose Send. If the message is sent successfully, the response pane shows a status of 200 OK. You see a response that resembles the example in the following image.
Tutorial: Setting up an SMS registration system
SMS messages (text messages) are a great way to send time-sensitive messages to your customers. These days, many people keep their phones nearby at all times. Also, SMS messages tend to capture people's attention more than push notifications, emails, or phone calls.
A common way to capture customers' mobile phone numbers is to use a web-based form. After you verify the customer's phone number and confirm their subscription, you can start sending promotional, transactional, and informational SMS messages to that customer.
This tutorial shows you how to set up a web form to capture customers' contact information. The web form sends this information to Amazon Pinpoint. Next, Amazon Pinpoint verifies that the phone number is valid, and captures other metadata that's related to the phone number. After that, Amazon Pinpoint sends the customer a message asking them to confirm their subscription. After the customer confirms their subscription, Amazon Pinpoint opts them in to receiving your messages.
The following architecture diagram shows the flow of data in this solution.
About double opt-in
About double opt-in
This tutorial shows you how to set up a double opt-in system in Amazon Pinpoint that uses two-way SMS messaging.
In an SMS double opt-in system, a customer provides you with their phone number by submitting it in a web form or within your app. When you receive the request from the customer, you create a new endpoint in Amazon Pinpoint. The new endpoint should be opted out of your communications. Next, you send a message to that phone number. In your message, you ask the recipient to confirm their subscription by replying with a specific word or phrase (such as "Yes" or "Confirm"). If the customer responds to the message with the word or phrase that you specified, you change the endpoint's status to opted-in. Otherwise, if the customer doesn't respond or they respond with a different word or phrase, you can leave the endpoint with a status of opted-out.
About this solution
This section contains information about the solution that you're building in this tutorial.
Intended Audience
This tutorial is intended for developer and system implementer audiences. You don't have to be familiar with Amazon Pinpoint to complete the steps in this tutorial. However, you should be comfortable managing IAM policies, creating Lambda functions in Node.js, and deploying web content.
Features Used
This tutorial includes usage examples for the following Amazon Pinpoint features:
• Sending transactional SMS messages
• Obtaining information about phone numbers by using phone number validation
• Receiving incoming SMS messages by using two-way SMS messaging
• Creating dynamic segments
• Creating campaigns
• Interacting with the Amazon Pinpoint API by using AWS Lambda
Time Required
It should take about one hour to complete this tutorial. After you implement this solution, there are additional steps that you can take to refine the solution to suit your unique use case.
Prerequisites
Regional Restrictions
This tutorial requires you to lease a long code by using the Amazon Pinpoint console. You can use the Amazon Pinpoint console to lease dedicated long codes that are based in several countries. However, only long codes that are based in the United States or Canada can be used to send SMS messages. (You can use long codes that are based in other countries and regions to send voice messages.)
We developed the code examples in this tutorial with this restriction in mind. For example, the code examples assume that the recipient's phone number always has 10 digits, and a country code of 1. If you implement this solution in countries or regions other than the United States or Canada, you have to modify the code examples appropriately.
Resource Usage Costs
There's no charge for creating an AWS account. However, by implementing this solution, you might incur the following costs:
• Long code lease costs – To complete this tutorial, you have to lease a long code. Long codes that are based in the United States (excluding US Territories) and Canada cost $1.00 per month.
• Phone number validation usage – The solution in this tutorial uses the phone number validation feature of Amazon Pinpoint to verify that each number you receive is valid and properly formatted, and to obtain additional information about the phone number. You pay $0.006 for each phone number validation request.
• Message sending costs – The solution in this tutorial sends outbound SMS messages. You pay for each message that you send through Amazon Pinpoint. The price that you pay for each message depends on the country or region of the recipient. If you send messages to recipients in the United States (excluding US Territories), you pay $0.00645 per message. If you send messages to recipients in Canada, you pay between $0.00109–$0.02, depending on the recipient's carrier and location.
• Message receiving costs – This solution also receives and processes incoming SMS messages. You pay for each incoming message that's sent to phone numbers that are associated with your Amazon Pinpoint account. The price that you pay depends on where the receiving phone number is based. If your receiving number is based in the United States (excluding US Territories), you pay $0.0075 per incoming message. If your number is based in Canada, you pay $0.00155 per incoming message.
• Lambda usage – This solution uses two Lambda functions that interact with the Amazon Pinpoint API.
When you call a Lambda function, you're charged based on the number of requests for your functions, for the time that it takes for your code to execute, and for the amount of memory that your functions use. The functions in this tutorial use very little memory, and typically run for 1–3 seconds. Some or all of your usage of this solution might fall under the Lambda free usage tier. For more information, see Lambda pricing.
• API Gateway usage – The web form in this solution calls an API that's managed by API Gateway. For every million calls to API Gateway, you pay $3.50–$3.70, depending on which AWS Region you use Amazon Pinpoint in. For more information, see API Gateway pricing.
• Web hosting costs – This solution includes a web-based form that you have to host on your website.
The price that you pay for hosting this content depends on your web hosting provider.
NoteAll prices shown in this list are in US Dollars (USD).
Next: Prerequisites (p. 19)
Prerequisites
Before you begin this tutorial, you have to complete the following prerequisites:
• You have to have an AWS account. To create an AWS account, go to https://console.aws.amazon.com/
and choose Create a new AWS account.