Campaign

A campaign is a messaging initiative that engages a specific
segment of users for an Amazon Pinpoint application. The information represented by
this resource includes the segment of users that a campaign sends messages to, the
message that a campaign delivers, and the schedule on which a campaign runs.

You can use the Campaign resource to retrieve information about, update, or delete
a specific campaign. To create a campaign, use the Campaigns resource and send a POST
request to the /apps/application-id/campaigns
URI.

URI

/v1/apps/application-id/campaigns/campaign-id

HTTP Methods

GET

Operation ID: GetCampaign

Retrieves information about the status, configuration, and other settings for a
campaign.

Example MessageBody

Properties

AttributeDimension

Specifies the criteria for including or excluding endpoints from a segment.

Property

Type

Required

Description

AttributeType

string

Values: INCLUSIVE | EXCLUSIVE

False

The type of segment dimension to use. Valid values are: INCLUSIVE,
endpoints that match the criteria are included in the segment; and,
EXCLUSIVE, endpoints that match the criteria are excluded from the
segment.

Values

Array of type string

True

The criteria values to use for the segment dimension. Depending on the value of
the AttributeType property, endpoints are included or excluded from the
segment if their attribute values match the criteria values.

CampaignEmailMessage

Specifies the content and "From" address for an email message that's sent to
recipients of a campaign.

Property

Type

Required

Description

Title

string

True

The subject line, or title, of the email.

Body

string

False

The body of the email for recipients whose email clients don't support HTML
content.

HtmlBody

string

True

The body of the email, in HTML format, for recipients whose email clients support
HTML content.

FromAddress

string

False

The verified email address to send the email from. The default address is the
FromAddress specified for the email channel for the
application.

The type of event that causes the campaign to be sent. Valid values are:
SYSTEM, sends the campaign when a system event occurs; and,
ENDPOINT, sends the campaign when an endpoint event (Events resource) occurs.

CampaignHook

Specifies the AWS Lambda function to use as a code hook for a campaign.

Property

Type

Required

Description

LambdaFunctionName

string

False

The name or Amazon Resource Name (ARN) of the AWS Lambda function that Amazon
Pinpoint invokes to send messages for a campaign.

WebUrl

string

False

The web URL that Amazon Pinpoint calls to invoke the AWS Lambda function over
HTTPS.

Mode

string

Values: DELIVERY | FILTER

False

Specifies which Lambda mode to use when invoking the AWS Lambda function.

CampaignLimits

Specifies the limits on the messages that a campaign can send.

Property

Type

Required

Description

Daily

integer

False

The maximum number of messages that a campaign can send to a single endpoint
during a 24-hour period. The maximum value is 100.

Total

integer

False

The maximum number of messages that a campaign can send to a single endpoint
during the course of the campaign. The maximum value is 100.

MessagesPerSecond

integer

False

The maximum number of messages that a campaign can send each second. The minimum
value is 50. The maximum value is 20,000.

MaximumDuration

integer

False

The maximum amount of time, in seconds, that a campaign can attempt to deliver a
message after the scheduled start time for the campaign. The minimum value is 60
seconds.

CampaignResponse

Provides information about the status, configuration, and other settings for a
campaign.

Property

Type

Required

Description

TreatmentName

string

False

The custom name of a variation of the campaign that's used for A/B testing.

TreatmentDescription

string

False

The custom description of a variation of the campaign that's used for A/B
testing.

The current status of the campaign's default treatment. This value exists only for
campaigns that have more than one treatment, to support A/B testing.

Version

integer

False

The version number of the campaign.

IsPaused

boolean

False

Specifies whether the campaign is paused. A paused campaign doesn't run unless you
resume it by changing this value to false.

Arn

string

True

The Amazon Resource Name (ARN) of the campaign.

tags

object

False

A string-to-string map of key-value pairs that identifies the tags that are
associated with the campaign. Each tag consists of a required tag key and an
associated tag value.

CampaignSmsMessage

Specifies the content and settings for an SMS message that's sent to recipients of
a campaign.

Property

Type

Required

Description

Body

string

False

The body of the SMS message.

MessageType

string

Values: TRANSACTIONAL | PROMOTIONAL

False

The type of SMS message. Valid values are: TRANSACTIONAL, the message
is critical or time-sensitive, such as a one-time password that supports a customer
transaction; and, PROMOTIONAL, the message isn't critical or
time-sensitive, such as a marketing message.

SenderId

string

False

The sender ID to display on recipients' devices when they receive the SMS
message.

CampaignState

The status of the campaign, or the status of a treatment that belongs to an A/B
test campaign. If a campaign uses A/B testing, the campaign has a status of
COMPLETED only when all campaign treatments have a status of
COMPLETED.

EventDimensions

Specifies the dimensions for an event filter that determines when a campaign is
sent.

The name of the event that causes the campaign to be sent. This can be a standard
type of event that Amazon Pinpoint generates, such as _session.start, or
a custom event that's specific to your app.

Attributes

object

False

One or more custom attributes that your app reports to Amazon Pinpoint. You can
use these attributes as selection criteria when you create an event filter.

Metrics

object

False

One or more custom metrics that your app reports to Amazon Pinpoint. You can use
these metrics as selection criteria when you create an event filter.

Message

Specifies the content and settings for a push notification that's sent to
recipients of a campaign.

Property

Type

Required

Description

Title

string

False

The title to display above the notification message on a recipient's
device.

Body

string

False

The body of the notification message. The maximum number of characters is
200.

ImageUrl

string

False

The URL of an image to display in the push notification.

ImageIconUrl

string

False

The URL of the image to display as the push-notification icon, such as the icon
for the app.

ImageSmallIconUrl

string

False

The URL of the image to display as the small, push-notification icon, such as a
small version of the icon for the app.

MediaUrl

string

False

The URL of the image or video to display in the push notification.

Action

string

Values: OPEN_APP | DEEP_LINK | URL

True

The action to occur if a recipient taps the push notification. Valid values
are:

OPEN_APP - Your app opens or it becomes the foreground app if it was sent to
the background. This is the default action.

DEEP_LINK - Your app opens and displays a designated user interface in the
app. This setting uses the deep-linking features of iOS and Android.

URL - The default mobile browser on the recipient's device opens and loads
the web page at a URL that you specify.

Url

string

False

The URL to open in a recipient's default mobile browser, if a recipient taps the
push notification and the value of the Action property is
URL.

SilentPush

boolean

False

Specifies whether the notification is a silent push notification, which is a push
notification that doesn't display on a recipient's device. Silent push notifications
can be used for cases such as updating an app's configuration, displaying messages
in
an in-app message center, or supporting phone home functionality.

JsonBody

string

False

The JSON payload to use for a silent push notification.

RawContent

string

False

The raw, JSON-formatted string to use as the payload for the notification message.
This value overrides other values for the message.

TimeToLive

integer

False

The number of seconds that the push-notification service should keep the message,
if the service is unable to deliver the notification the first time. This value is
converted to an expiration value when it's sent to a push-notification service. If
this value is 0, the service treats the notification as if it expires
immediately and the service doesn't store or try to deliver the notification
again.

This value doesn't apply to messages that are sent through the Amazon Device
Messaging (ADM) service.

QuietTime

Specifies the start and end times that define a time range when messages aren't
sent to endpoints.

Property

Type

Required

Description

Start

string

False

The specific time when quiet time begins. This value has to use 24-hour notation
and be in HH:MM format, where HH is the hour (with a leading zero, if applicable)
and
MM is the minutes. For example, use 02:30 to represent 2:30 AM, or
14:30 to represent 2:30 PM.

End

string

False

The specific time when quiet time ends. This value has to use 24-hour notation and
be in HH:MM format, where HH is the hour (with a leading zero, if applicable) and
MM
is the minutes. For example, use 02:30 to represent 2:30 AM, or
14:30 to represent 2:30 PM.

Schedule

Specifies the schedule settings for a campaign.

Property

Type

Required

Description

StartTime

string

True

The scheduled time, in ISO 8601 format, for the campaign to begin.

EndTime

string

False

The scheduled time, in ISO 8601 format, for the campaign to end.

Frequency

string

Values: ONCE | HOURLY | DAILY | WEEKLY | MONTHLY | EVENT

False

Specifies how often the campaign is sent or whether the campaign is sent in
response to a specific event.

IsLocalTime

boolean

False

Specifies whether the start and end times for the campaign schedule use each
recipient's local time. To base the schedule on each recipient's local time, set this
value to true.

The type of event that causes the campaign to be sent, if the value of the
Frequency property is EVENT.

SetDimension

Specifies the dimension type and values for a segment.

Property

Type

Required

Description

DimensionType

string

Values: INCLUSIVE | EXCLUSIVE

False

The type of segment dimension to use. Valid values are: INCLUSIVE,
endpoints that match the criteria are included in the segment; and,
EXCLUSIVE, endpoints that match the criteria are excluded from the
segment.

Values

Array of type string

True

The criteria values for the segment dimension to use. Depending on the value of
the DimensionType property, endpoints are included or excluded from the
segment if their attribute values match the criteria values.

TreatmentResource

Specifies the settings for a campaign treatment. A treatment is a variation of a
campaign that's used for A/B testing of a campaign.

Property

Type

Required

Description

TreatmentName

string

False

The custom name of the treatment. A treatment is a variation of a campaign that's
used for A/B testing of a campaign.

The name of the message template that defines the content to use in the message
for the treatment. This value must be an exact match to the name of an existing
message template. In addition, a version of the message template
(TemplateType property) must exist for each channel that you want to
send the message through. Otherwise, an error occurs.

SubstitutionsJson

string

False

A JSON string that maps message variable values for the treatment. Amazon Pinpoint
merges these values with endpoint-specific values. The endpoint-specific values take
precedence.

SizePercent

integer

True

The allocated percentage of users (segment members) that the treatment is sent
to.

The name of the message template that defines the content to use in messages for
the campaign. This value must be an exact match to the name of an existing message
template. In addition, a version of the message template (TemplateType
property) must exist for each channel that you want to send the message through.
Otherwise, an error occurs.

SubstitutionsJson

string

False

A JSON string that maps message variable values for the campaign. Amazon Pinpoint
merges these values with endpoint-specific values. The endpoint-specific values take
precedence.

SegmentId

string

False

The unique identifier for the segment to associate with the campaign.

SegmentVersion

integer

False

The version of the segment to associate with the campaign.

IsPaused

boolean

False

Specifies whether to pause the campaign. A paused campaign doesn't run unless you
resume it by setting this value to false.

The name of the message template that defines the content to use in the message
for the treatment. This value must be an exact match to the name of an existing
message template. In addition, a version of the message template
(TemplateType property) must exist for each channel that you want to
send the message through. Otherwise, an error occurs.

SubstitutionsJson

string

False

A JSON string that maps message variable values for the treatment. Amazon Pinpoint
merges these values with endpoint-specific values. The endpoint-specific values take
precedence.

SizePercent

integer

True

The allocated percentage of users (segment members) to send the treatment
to.

See Also

For more information about using this API in one of the language-specific AWS SDKs
and references, see the following: