**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. # Create or import segments in Amazon Pinpoint A user *segment* represents a subset of users based on shared characteristics, such as how recently the users have used your app or which device platform they use. A segment designates which users receive the messages delivered by a campaign. Define segments so that you can reach the right audience when you want to invite users back to your app, make special offers, or otherwise increase user engagement and purchasing. After you create a segment, you can use it in one or more campaigns. A campaign delivers tailored messages to the users in the segment. For more information, see [Segments](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-segments.html). **Topics** + [Build segments in Amazon Pinpoint](segments-dimensional.md) + [Import segments in Amazon Pinpoint](segments-importing.md) + [Customize Amazon Pinpoint segments using an AWS Lambda function](segments-dynamic.md) # Build segments in Amazon Pinpoint To reach the intended audience for a campaign, build a segment based on the data reported by your app. For example, to reach users who haven’t used your app recently, you can define a segment for users who haven’t used your app in the last 30 days. For more code examples, see [Code examples](https://docs.aws.amazon.com/pinpoint/latest/developerguide/service_code_examples.html). ## Build segments with the AWS SDK for Java The following example demonstrates how to build a segment with the AWS SDK for Java. The example creates a segment of users who's team is the `Lakers` and have been active in the past 30 days. Once the segment has been built you can use it as part of a campaign or journey. For an example of using a segment with a campaign, see [Create Amazon Pinpoint campaigns programmatically](campaigns.md). ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.pinpoint.PinpointClient; import software.amazon.awssdk.services.pinpoint.model.AttributeDimension; import software.amazon.awssdk.services.pinpoint.model.SegmentResponse; import software.amazon.awssdk.services.pinpoint.model.AttributeType; import software.amazon.awssdk.services.pinpoint.model.RecencyDimension; import software.amazon.awssdk.services.pinpoint.model.SegmentBehaviors; import software.amazon.awssdk.services.pinpoint.model.SegmentDemographics; import software.amazon.awssdk.services.pinpoint.model.SegmentLocation; import software.amazon.awssdk.services.pinpoint.model.SegmentDimensions; import software.amazon.awssdk.services.pinpoint.model.WriteSegmentRequest; import software.amazon.awssdk.services.pinpoint.model.CreateSegmentRequest; import software.amazon.awssdk.services.pinpoint.model.CreateSegmentResponse; import software.amazon.awssdk.services.pinpoint.model.PinpointException; import java.util.HashMap; import java.util.Map; ``` ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.pinpoint.PinpointClient; import software.amazon.awssdk.services.pinpoint.model.AttributeDimension; import software.amazon.awssdk.services.pinpoint.model.SegmentResponse; import software.amazon.awssdk.services.pinpoint.model.AttributeType; import software.amazon.awssdk.services.pinpoint.model.RecencyDimension; import software.amazon.awssdk.services.pinpoint.model.SegmentBehaviors; import software.amazon.awssdk.services.pinpoint.model.SegmentDemographics; import software.amazon.awssdk.services.pinpoint.model.SegmentLocation; import software.amazon.awssdk.services.pinpoint.model.SegmentDimensions; import software.amazon.awssdk.services.pinpoint.model.WriteSegmentRequest; import software.amazon.awssdk.services.pinpoint.model.CreateSegmentRequest; import software.amazon.awssdk.services.pinpoint.model.CreateSegmentResponse; import software.amazon.awssdk.services.pinpoint.model.PinpointException; import java.util.HashMap; import java.util.Map; /** * Before running this Java V2 code example, set up your development * environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html */ public class CreateSegment { public static void main(String[] args) { final String usage = """ Usage: Where: appId - The application ID to create a segment for. """; if (args.length != 1) { System.out.println(usage); System.exit(1); } String appId = args[0]; PinpointClient pinpoint = PinpointClient.builder() .region(Region.US_EAST_1) .build(); SegmentResponse result = createSegment(pinpoint, appId); System.out.println("Segment " + result.name() + " created."); System.out.println(result.segmentType()); pinpoint.close(); } public static SegmentResponse createSegment(PinpointClient client, String appId) { try { Map segmentAttributes = new HashMap<>(); segmentAttributes.put("Team", AttributeDimension.builder() .attributeType(AttributeType.INCLUSIVE) .values("Lakers") .build()); RecencyDimension recencyDimension = RecencyDimension.builder() .duration("DAY_30") .recencyType("ACTIVE") .build(); SegmentBehaviors segmentBehaviors = SegmentBehaviors.builder() .recency(recencyDimension) .build(); SegmentDemographics segmentDemographics = SegmentDemographics .builder() .build(); SegmentLocation segmentLocation = SegmentLocation .builder() .build(); SegmentDimensions dimensions = SegmentDimensions .builder() .attributes(segmentAttributes) .behavior(segmentBehaviors) .demographic(segmentDemographics) .location(segmentLocation) .build(); WriteSegmentRequest writeSegmentRequest = WriteSegmentRequest.builder() .name("MySegment") .dimensions(dimensions) .build(); CreateSegmentRequest createSegmentRequest = CreateSegmentRequest.builder() .applicationId(appId) .writeSegmentRequest(writeSegmentRequest) .build(); CreateSegmentResponse createSegmentResult = client.createSegment(createSegmentRequest); System.out.println("Segment ID: " + createSegmentResult.segmentResponse().id()); System.out.println("Done"); return createSegmentResult.segmentResponse(); } catch (PinpointException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } return null; } } ``` When you run this example, the following is printed to the console window of your IDE: ``` Segment ID: 09cb2967a82b4a2fbab38fead8d1f4c4 ``` For the full SDK example, see [CreateSegment.java](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javav2/example_code/pinpoint/src/main/java/com/example/pinpoint/CreateSegment.java) on [GitHub](https://github.com/). # Import segments in Amazon Pinpoint With Amazon Pinpoint, you can define a user segment by importing information about the endpoints that belong to the segment. An *endpoint* is a single messaging destination, such as a mobile push device token, a mobile phone number, or an email address. Importing segments is useful if you've already created segments of your users outside of Amazon Pinpoint but you want to engage your users with Amazon Pinpoint campaigns. When you import a segment, Amazon Pinpoint gets the segment's endpoints from Amazon Simple Storage Service (Amazon S3). Before you import, you add the endpoints to Amazon S3, and you create an IAM role that grants Amazon Pinpoint access to Amazon S3. Then, you give Amazon Pinpoint the Amazon S3 location where the endpoints are stored, and Amazon Pinpoint adds each endpoint to the segment. To create the IAM role, see [IAM role for importing endpoints or segments](permissions-import-segment.md). For information about importing a segment by using the Amazon Pinpoint console, see [Importing segments](https://docs.aws.amazon.com/pinpoint/latest/userguide/segments-importing.html) in the *Amazon Pinpoint User Guide*. For more code examples, see [Code examples](https://docs.aws.amazon.com/pinpoint/latest/developerguide/service_code_examples.html). ## Import a segment with the AWS SDK for Java The following example demonstrates how to import a segment by using the AWS SDK for Java. ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.pinpoint.PinpointClient; import software.amazon.awssdk.services.pinpoint.model.CreateImportJobRequest; import software.amazon.awssdk.services.pinpoint.model.ImportJobResponse; import software.amazon.awssdk.services.pinpoint.model.ImportJobRequest; import software.amazon.awssdk.services.pinpoint.model.Format; import software.amazon.awssdk.services.pinpoint.model.CreateImportJobResponse; import software.amazon.awssdk.services.pinpoint.model.PinpointException; ``` ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.pinpoint.PinpointClient; import software.amazon.awssdk.services.pinpoint.model.CreateImportJobRequest; import software.amazon.awssdk.services.pinpoint.model.ImportJobResponse; import software.amazon.awssdk.services.pinpoint.model.ImportJobRequest; import software.amazon.awssdk.services.pinpoint.model.Format; import software.amazon.awssdk.services.pinpoint.model.CreateImportJobResponse; import software.amazon.awssdk.services.pinpoint.model.PinpointException; /** * Before running this Java V2 code example, set up your development * environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html */ public class ImportSegment { public static void main(String[] args) { final String usage = """ Usage: \s Where: appId - The application ID to create a segment for. bucket - The name of the Amazon S3 bucket that contains the segment definitons. key - The key of the S3 object. roleArn - ARN of the role that allows Amazon Pinpoint to access S3. You need to set trust management for this to work. See https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html """; if (args.length != 4) { System.out.println(usage); System.exit(1); } String appId = args[0]; String bucket = args[1]; String key = args[2]; String roleArn = args[3]; PinpointClient pinpoint = PinpointClient.builder() .region(Region.US_EAST_1) .build(); ImportJobResponse response = createImportSegment(pinpoint, appId, bucket, key, roleArn); System.out.println("Import job for " + bucket + " submitted."); System.out.println("See application " + response.applicationId() + " for import job status."); System.out.println("See application " + response.jobStatus() + " for import job status."); pinpoint.close(); } public static ImportJobResponse createImportSegment(PinpointClient client, String appId, String bucket, String key, String roleArn) { try { ImportJobRequest importRequest = ImportJobRequest.builder() .defineSegment(true) .registerEndpoints(true) .roleArn(roleArn) .format(Format.JSON) .s3Url("s3://" + bucket + "/" + key) .build(); CreateImportJobRequest jobRequest = CreateImportJobRequest.builder() .importJobRequest(importRequest) .applicationId(appId) .build(); CreateImportJobResponse jobResponse = client.createImportJob(jobRequest); return jobResponse.importJobResponse(); } catch (PinpointException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } return null; } } ``` For the full SDK example, see [ImportingSegments.java](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javav2/example_code/pinpoint/src/main/java/com/example/pinpoint/ImportSegment.java/) on [GitHub](https://github.com/). # Customize Amazon Pinpoint segments using an AWS Lambda function | | | --- | | This is prerelease documentation for a feature in public beta release. It is subject to change. | You can use AWS Lambda to tailor how an Amazon Pinpoint campaign engages your target audience. With AWS Lambda, you can modify the campaign's segment the moment when Amazon Pinpoint sends the campaign's message. AWS Lambda is a compute service that you can use to run code without provisioning or managing servers. You package your code and upload it to Lambda as *Lambda functions*. Lambda runs a function when the function is invoked, which might be done manually by you or automatically in response to events. For more information, see the [AWS Lambda Developer Guide](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html). To assign a Lambda function to a campaign, you define the campaign's `CampaignHook` settings by using the [Campaign](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id.html) resource in the Amazon Pinpoint API. These settings include the Lambda function name. They also include the `CampaignHook` mode, which specifies whether Amazon Pinpoint receives a return value from the function. A Lambda function that you assign to a campaign is referred to as an Amazon Pinpoint *extension*. With the `CampaignHook` settings defined, Amazon Pinpoint automatically invokes the Lambda function when it runs the campaign, before it sends the campaign's message. When Amazon Pinpoint invokes the function, it provides *event data* about the message delivery. This data includes the campaign's segment, which is the list of endpoints that Amazon Pinpoint sends the message to. If the `CampaignHook` mode is set to `FILTER`, Amazon Pinpoint allows the function to modify and return the segment before sending the message. For example, the function might update the endpoint definitions with attributes that contain data from a source that is external to Amazon Pinpoint. Or, the function might filter the segment by removing certain endpoints, based on conditions in your function code. After Amazon Pinpoint receives the modified segment from your function, it sends the message to each of the segment's endpoints using the campaign's delivery channel. By processing your segments with AWS Lambda, you have more control over who you send messages to and what those messages contain. You can tailor your campaigns in real time, at the moment when campaign messages are sent. Filtering segments enables you to engage more narrowly defined subsets of your segments. Adding or updating endpoint attributes also enables you to make new data available for message variables. **Note** You can also use the `CampaignHook` settings to assign a Lambda function that handles the message delivery. This type of function is useful for delivering messages through custom channels that Amazon Pinpoint doesn't support, such as social media platforms. For more information, see [Create a custom channel in Amazon Pinpoint using a webhook or Lambda function](channels-custom.md). When invoking a Lambda hook using Amazon Pinpoint, the Lambda function must also be in the same region as the Amazon Pinpoint project. To modify campaign segments with AWS Lambda, first create a function that processes the event data sent by Amazon Pinpoint and returns a modified segment. Then, authorize Amazon Pinpoint to invoke the function by assigning a Lambda function policy. Finally, assign the function to one or more campaigns by defining `CampaignHook` settings. For more code examples, see [Code examples](https://docs.aws.amazon.com/pinpoint/latest/developerguide/service_code_examples.html). ## Event data When Amazon Pinpoint invokes your Lambda function, it provides the following payload as the event data: ``` { "MessageConfiguration": {Message configuration} "ApplicationId": ApplicationId, "CampaignId": CampaignId, "TreatmentId": TreatmentId, "ActivityId": ActivityId, "ScheduledTime": Scheduled Time, "Endpoints": { EndpointId: {Endpoint definition} . . . } } ``` AWS Lambda passes the event data to your function code. The event data provides the following attributes: + `MessageConfiguration` – Has the same structure as the `DirectMessageConfiguration` object of the [Messages](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-messages.html) resource in the Amazon Pinpoint API. + `ApplicationId` – The ID of the Amazon Pinpoint project that the campaign belongs to. + `CampaignId` – The ID of the Amazon Pinpoint campaign that the function is invoked for. + `TreatmentId` – The ID of a campaign variation that's used for A/B testing. + `ActivityId` – The ID of the activity that's being performed by the campaign. + `ScheduledTime` – The date and time, in ISO 8601 format, when the campaign's messages will be delivered. + `Endpoints` – A map that associates endpoint IDs with endpoint definitions. Each event data payload contains up to 50 endpoints. If the campaign segment contains more than 50 endpoints, Amazon Pinpoint invokes the function repeatedly, with up to 50 endpoints at a time, until all endpoints have been processed. ## Create a Lambda function To learn how to create a Lambda function, see [Getting started](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html) in the *AWS Lambda Developer Guide*. When you create your function, remember that message delivery fails in the following conditions: + The Lambda function takes longer than 15 seconds to return the modified segment. + Amazon Pinpoint can't decode the function's return value. + The function requires more than 3 attempts from Amazon Pinpoint to successfully invoke it. Amazon Pinpoint only accepts endpoint definitions in the function's return value. The function can't modify other elements in the event data. ### Example Lambda function Your Lambda function processes the event data sent by Amazon Pinpoint, and it returns the modified endpoints, as shown by the following example handler, written in Node.js: ``` 'use strict'; exports.handler = (event, context, callback) => { for (var key in event.Endpoints) { if (event.Endpoints.hasOwnProperty(key)) { var endpoint = event.Endpoints[key]; var attr = endpoint.Attributes; if (!attr) { attr = {}; endpoint.Attributes = attr; } attr["CreditScore"] = [ Math.floor(Math.random() * 200) + 650]; } } console.log("Received event:", JSON.stringify(event, null, 2)); callback(null, event.Endpoints); }; ``` Lambda passes the event data to the handler as the `event` parameter. In this example, the handler iterates through each endpoint in the `event.Endpoints` object, and it adds a new attribute, `CreditScore`, to the endpoint. The value of the `CreditScore` attribute is simply a random number. The `console.log()` statement logs the event in CloudWatch Logs. The `callback()` statement returns the modified endpoints to Amazon Pinpoint. Normally, the `callback` parameter is optional in Node.js Lambda functions, but it is required in this context because the function must return the updated endpoints to Amazon Pinpoint. Your function must return endpoints in the same format provided by the event data, which is a map that associates endpoint IDs with endpoint definitions, as in the following example: ``` { "eqmj8wpxszeqy/b3vch04sn41yw": { "ChannelType": "GCM", "Address": "4d5e6f1a2b3c4d5e6f7g8h9i0j1a2b3c", "EndpointStatus": "ACTIVE", "OptOut": "NONE", "Demographic": { "Make": "android" }, "EffectiveDate": "2017-11-02T21:26:48.598Z", "User": {} }, "idrexqqtn8sbwfex0ouscod0yto": { "ChannelType": "APNS", "Address": "1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f", "EndpointStatus": "ACTIVE", "OptOut": "NONE", "Demographic": { "Make": "apple" }, "EffectiveDate": "2017-11-02T21:26:48.598Z", "User": {} } } ``` The example function modifies and returns the `event.Endpoints` object that it received in the event data. Optionally, you can include the `TitleOverride` and `BodyOverride` attributes in the endpoint definitions that you return. **Note** When you use this solution to send messages, Amazon Pinpoint honors the `TitleOverride` and `BodyOverride` attributes only for endpoints where the value of the `ChannelType` attribute is one of the following: `ADM`, `APNS`, `APNS_SANDBOX`, `APNS_VOIP`, `APNS_VOIP_SANDBOX`, `BAIDU`, `GCM`, or `SMS`. Amazon Pinpoint **doesn't** honor these attributes for endpoints where the value of the `ChannelType` attribute is `EMAIL`. ## Assign a Lambda function policy Before you can use your Lambda function to process your endpoints, you must authorize Amazon Pinpoint to invoke your Lambda function. To grant invocation permission, assign a *Lambda function policy* to the function. A Lambda function policy is a resource-based permissions policy that designates which entities can use your function and what actions those entities can take. For more information, see [Using resource-based policies for AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html) in the *AWS Lambda Developer Guide*. ### Example function policy The following policy grants permission to the Amazon Pinpoint service principal to use the `lambda:InvokeFunction` action for a specific campaign (*campaign-id*): ``` { "Sid": "sid", "Effect": "Allow", "Principal": { "Service": "pinpoint.us-east-1.amazonaws.com" }, "Action": "lambda:InvokeFunction", "Resource": "{arn:aws:lambda:us-east-1:account-id:function:function-name}", "Condition": { "StringEquals": { "AWS:SourceAccount": "111122223333" }, "ArnLike": { "AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/campaign-id" } } } ``` Your function policy requires a `Condition` block that includes an `AWS:SourceArn` key. This code states which Amazon Pinpoint campaign is allowed to invoke the function. In this example, the policy grants permission to only a single campaign. The `Condition` block must also include an `AWS:SourceAccount` key, which controls which AWS account can invoke the action. To write a more generic policy, use a multicharacter match wildcard (\$1). For example, you can use the following `Condition` block to allow any campaign in a specific Amazon Pinpoint project (*application-id*) to invoke the function: ``` ... "Condition": { "StringEquals": { "AWS:SourceAccount": "111122223333" }, "ArnLike": { "AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/*" } } ... ``` If you want the Lambda function to be the default function that's used by all the campaigns for a project, we recommend that you configure the `Condition` block for the policy in the preceding way. For information about setting a Lambda function as the default for all campaigns in a project, see [Assign a Lambda function to a campaign](#segments-dynamic-assign). ### Grant Amazon Pinpoint invocation permission You can use the AWS Command Line Interface (AWS CLI) to add permissions to the Lambda function policy assigned to your Lambda function. To allow Amazon Pinpoint to invoke a function for a specific campaign, use the Lambda [https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) command, as shown in the following example: ``` $ aws lambda add-permission \ > --function-name function-name \ > --statement-id sid \ > --action lambda:InvokeFunction \ > --principal pinpoint.us-east-1.amazonaws.com \ > --source-account 111122223333 > --source-arn arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/campaign-id ``` You can look up your campaign IDs by using the [get-campaigns](https://docs.aws.amazon.com/cli/latest/reference/pinpoint/get-campaigns.html) command in the AWS CLI. You can also look up your application ID by using the [get-apps](https://docs.aws.amazon.com/cli/latest/reference/pinpoint/get-apps.html) command. When you run the Lambda `add-permission` command, Lambda returns the following output: ``` { "Statement": "{\"Sid\":\"sid\", \"Effect\":\"Allow\", \"Principal\":{\"Service\":\"pinpoint.us-east-1.amazonaws.com\"}, \"Action\":\"lambda:InvokeFunction\", \"Resource\":\"arn:aws:lambda:us-east-1:111122223333:function:function-name\", \"Condition\": {\"ArnLike\": {\"AWS:SourceArn\": \"arn:aws:mobiletargeting:us-east-1:111122223333:apps/application-id/campaigns/campaign-id\"}} {\"StringEquals\": {\"AWS:SourceAccount\": \"111122223333\"}}} } ``` The `Statement` value is a JSON string version of the statement that was added to the Lambda function policy. ## Assign a Lambda function to a campaign You can assign a Lambda function to an individual Amazon Pinpoint campaign. Or, you can set the Lambda function as the default used by all campaigns for a project, except for those campaigns to which you assign a function individually. To assign a Lambda function to an individual campaign, use the Amazon Pinpoint API to create or update a [https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns.html](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns.html) object, and define its `CampaignHook` attribute. To set a Lambda function as the default for all campaigns in a project, create or update the [https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-settings.html](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-settings.html) resource for that project, and define its `CampaignHook` object. In both cases, set the following `CampaignHook` attributes: + `LambdaFunctionName` – The name or ARN of the Lambda function that Amazon Pinpoint invokes before sending messages for the campaign. + `Mode` – Set to `FILTER`. With this mode, Amazon Pinpoint invokes the function and waits for it to return the modified endpoints. After receiving them, Amazon Pinpoint sends the message. Amazon Pinpoint waits for up to 15 seconds before failing the message delivery. With `CampaignHook` settings defined for a campaign, Amazon Pinpoint invokes the specified Lambda function before sending the campaign's messages. Amazon Pinpoint waits to receive the modified endpoints from the function. If Amazon Pinpoint receives the updated endpoints, it proceeds with the message delivery, using the updated endpoint data.