Menu
Amazon Pinpoint
REST API Reference

Campaign

A campaign is a messaging initiative that engages a specific segment of end users. The information represented by this resource includes the segment that the campaign reaches out to, the message that it delivers, and the schedule on which it runs. You can use this resource to look up, update, or delete a campaign.

URI

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

HTTP Methods

DELETE

Deletes a campaign.

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

campaign-id

true

string

Response

Status Code Schema

200

CampaignResponse

GET

Returns information about a campaign.

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

campaign-id

true

string

Response

Status Code Schema

200

CampaignResponse

PUT

Use to update a campaign.

Body

Name Required Type

WriteCampaignRequest

true

WriteCampaignRequest

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

campaign-id

true

string

Response

Status Code Schema

200

CampaignResponse

Errors

Errors

Status Code Schema Error Type

400

MessageBody

BadRequestException

403

MessageBody

ForbiddenException

404

MessageBody

NotFoundException

405

MessageBody

MethodNotAllowedException

429

MessageBody

TooManyRequestsException

500

MessageBody

InternalServerErrorException

Schemas

Request Schemas

Example WriteCampaignRequest

{ "TreatmentName": "string", "TreatmentDescription": "string", "MessageConfiguration": { "DefaultMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "APNSMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "GCMMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "ADMMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "BaiduMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "EmailMessage": { "Title": "string", "Body": "string", "HtmlBody": "string", "FromAddress": "string" }, "SMSMessage": { "Body": "string", "MessageType": "TRANSACTIONAL", "SenderId": "string" } }, "Schedule": { "StartTime": "string", "EndTime": "string", "Frequency": "ONCE", "IsLocalTime": true, "Timezone": "string", "QuietTime": { "Start": "string", "End": "string" } }, "SegmentId": "string", "SegmentVersion": 0, "IsPaused": true, "AdditionalTreatments": [ { "TreatmentName": "string", "TreatmentDescription": "string", "MessageConfiguration": { "DefaultMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "APNSMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "GCMMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "ADMMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "BaiduMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "EmailMessage": { "Title": "string", "Body": "string", "HtmlBody": "string", "FromAddress": "string" }, "SMSMessage": { "Body": "string", "MessageType": "TRANSACTIONAL", "SenderId": "string" } }, "Schedule": { "StartTime": "string", "EndTime": "string", "Frequency": "ONCE", "IsLocalTime": true, "Timezone": "string", "QuietTime": { "Start": "string", "End": "string" } }, "SizePercent": 0 } ], "HoldoutPercent": 0, "Limits": { "Daily": 0, "Total": 0, "MessagesPerSecond": 0, "MaximumDuration": 0 }, "Name": "string", "Hook": { "LambdaFunctionName": "string", "WebUrl": "string", "Mode": "DELIVERY" }, "Description": "string" }

Response Schemas

Example CampaignResponse

{ "TreatmentName": "string", "TreatmentDescription": "string", "MessageConfiguration": { "DefaultMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "APNSMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "GCMMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "ADMMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "BaiduMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "EmailMessage": { "Title": "string", "Body": "string", "HtmlBody": "string", "FromAddress": "string" }, "SMSMessage": { "Body": "string", "MessageType": "TRANSACTIONAL", "SenderId": "string" } }, "Schedule": { "StartTime": "string", "EndTime": "string", "Frequency": "ONCE", "IsLocalTime": true, "Timezone": "string", "QuietTime": { "Start": "string", "End": "string" } }, "Id": "string", "ApplicationId": "string", "CreationDate": "string", "LastModifiedDate": "string", "SegmentId": "string", "SegmentVersion": 0, "AdditionalTreatments": [ { "TreatmentName": "string", "TreatmentDescription": "string", "MessageConfiguration": { "DefaultMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "APNSMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "GCMMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "ADMMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "BaiduMessage": { "Title": "string", "Body": "string", "ImageUrl": "string", "ImageIconUrl": "string", "ImageSmallIconUrl": "string", "MediaUrl": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "JsonBody": "string", "RawContent": "string" }, "EmailMessage": { "Title": "string", "Body": "string", "HtmlBody": "string", "FromAddress": "string" }, "SMSMessage": { "Body": "string", "MessageType": "TRANSACTIONAL", "SenderId": "string" } }, "Schedule": { "StartTime": "string", "EndTime": "string", "Frequency": "ONCE", "IsLocalTime": true, "Timezone": "string", "QuietTime": { "Start": "string", "End": "string" } }, "SizePercent": 0, "Id": "string", "State": { "CampaignStatus": "SCHEDULED" } } ], "HoldoutPercent": 0, "Name": "string", "Limits": { "Daily": 0, "Total": 0, "MessagesPerSecond": 0, "MaximumDuration": 0 }, "Description": "string", "Hook": { "LambdaFunctionName": "string", "WebUrl": "string", "Mode": "DELIVERY" }, "State": { "CampaignStatus": "SCHEDULED" }, "DefaultState": { "CampaignStatus": "SCHEDULED" }, "Version": 0, "IsPaused": true }

Example MessageBody

{ "RequestID": "string", "Message": "string" }

Attributes

WriteCampaignRequest

Attribute Type Description

AdditionalTreatments

array

Treatments that are defined in addition to the default treatment.

Description

string

A description of the campaign.

HoldoutPercent

integer

The allocated percentage of end users who will not receive messages from this campaign.

Hook

CampaignHook

Campaign hook information.

IsPaused

boolean

Indicates whether the campaign is paused. A paused campaign does not send messages unless you resume it by setting IsPaused to false.

Limits

CampaignLimits

The campaign limits settings.

MessageConfiguration

MessageConfiguration

The message configuration settings.

Name

string

The custom name of the campaign.

Schedule

Schedule

The campaign schedule.

SegmentId

string

The ID of the segment to which the campaign sends messages.

SegmentVersion

integer

The version of the segment to which the campaign sends messages.

TreatmentDescription

string

A custom description for the treatment.

TreatmentName

string

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

WriteTreatmentResource

Attribute Type Description

MessageConfiguration

MessageConfiguration

The message configuration settings.

Schedule

Schedule

The campaign schedule.

SizePercent

integer

The allocated percentage of users for this treatment.

TreatmentDescription

string

A custom description for the treatment.

TreatmentName

string

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

MessageConfiguration

Attribute Type Description

ADMMessage

Message

The message that the campaign delivers to ADM channels. Overrides the default message.

APNSMessage

Message

The message that the campaign delivers to APNS channels. Overrides the default message.

BaiduMessage

Message

The message that the campaign delivers to Baidu channels. Overrides the default message.

DefaultMessage

Message

The default message for all channels.

EmailMessage

CampaignEmailMessage

The email message configuration.

GCMMessage

Message

The message that the campaign delivers to GCM channels. Overrides the default message.

SMSMessage

CampaignSmsMessage

The SMS message configuration.

Message

Attribute Type Description

Action

string

The action that occurs if the user taps a push notification delivered by the campaign: OPEN_APP - Your app launches, or it becomes the foreground app if it has been sent to the background. This is the default action.

DEEP_LINK - Uses deep linking features in iOS and Android to open your app and display a designated user interface within the app.

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

Body

string

The message body. Can include up to 140 characters.

ImageIconUrl

string

The URL that points to the icon image for the push notification icon, for example, the app icon.

ImageSmallIconUrl

string

The URL that points to the small icon image for the push notification icon, for example, the app icon.

ImageUrl

string

The URL that points to an image used in the push notification.

JsonBody

string

The JSON payload used for a silent push.

MediaUrl

string

The URL that points to the media resource, for example a .mp4 or .gif file.

RawContent

string

The Raw JSON formatted string to be used as the payload. This value overrides the message.

SilentPush

boolean

Indicates if the message should display on the users device.

Silent pushes can be used for Remote Configuration and Phone Home use cases.

Title

string

The message title that displays above the message on the user's device.

Url

string

The URL to open in the user's mobile browser. Used if the value for Action is URL.

CampaignEmailMessage

Attribute Type Description

Body

string

The email text body.

FromAddress

string

The email address used to send the email from. Defaults to use FromAddress specified in the Email Channel.

HtmlBody

string

The email html body.

Title

string

The email title (Or subject).

CampaignSmsMessage

Attribute Type Description

Body

string

The SMS text body.

MessageType

string

Is this is a transactional SMS message, otherwise a promotional message.

SenderId

string

Sender ID of sent message.

Schedule

Attribute Type Description

EndTime

string

The scheduled time that the campaign ends in ISO 8601 format.

Frequency

string

How often the campaign delivers messages.

Valid values: ONCE, HOURLY, DAILY, WEEKLY, MONTHLY

IsLocalTime

boolean

Indicates whether the campaign schedule takes effect according to each user's local time.

QuietTime

QuietTime

The time during which the campaign sends no messages.

StartTime

string

The scheduled time that the campaign begins in ISO 8601 format.

Timezone

string

The starting UTC offset for the schedule if the value for isLocalTime is true

Valid values: UTC UTC+01 UTC+02 UTC+03 UTC+03:30 UTC+04 UTC+04:30 UTC+05 UTC+05:30 UTC+05:45 UTC+06 UTC+06:30 UTC+07 UTC+08 UTC+09 UTC+09:30 UTC+10 UTC+10:30 UTC+11 UTC+12 UTC+13 UTC-02 UTC-03 UTC-04 UTC-05 UTC-06 UTC-07 UTC-08 UTC-09 UTC-10 UTC-11

QuietTime

Attribute Type Description

End

string

The default end time for quiet time in ISO 8601 format.

Start

string

The default start time for quiet time in ISO 8601 format.

CampaignHook

Attribute Type Description

LambdaFunctionName

string

Lambda function name or arn to be called for delivery

Mode

string

What mode Lambda should be invoked in.

WebUrl

string

Web URL to call for hook. If the URL has authentication specified it will be added as authentication to the request

CampaignLimits

Attribute Type Description

Daily

integer

The maximum number of messages that the campaign can send daily.

MaximumDuration

integer

The length of time (in seconds) that the campaign can run before it ends and message deliveries stop. This duration begins at the scheduled start time for the campaign. The minimum value is 60.

MessagesPerSecond

integer

The number of messages that the campaign can send per second. The minimum value is 50, and the maximum is 20000.

Total

integer

The maximum total number of messages that the campaign can send.

CampaignResponse

Attribute Type Description

AdditionalTreatments

array

Treatments that are defined in addition to the default treatment.

ApplicationId

string

The ID of the application to which the campaign applies.

CreationDate

string

The date the campaign was created in ISO 8601 format.

DefaultState

CampaignState

The status of the campaign's default treatment. Only present for A/B test campaigns.

Description

string

A description of the campaign.

HoldoutPercent

integer

The allocated percentage of end users who will not receive messages from this campaign.

Hook

CampaignHook

Campaign hook information.

Id

string

The unique campaign ID.

IsPaused

boolean

Indicates whether the campaign is paused. A paused campaign does not send messages unless you resume it by setting IsPaused to false.

LastModifiedDate

string

The date the campaign was last updated in ISO 8601 format.

Limits

CampaignLimits

The campaign limits settings.

MessageConfiguration

MessageConfiguration

The message configuration settings.

Name

string

The custom name of the campaign.

Schedule

Schedule

The campaign schedule.

SegmentId

string

The ID of the segment to which the campaign sends messages.

SegmentVersion

integer

The version of the segment to which the campaign sends messages.

State

CampaignState

The campaign status.

An A/B test campaign will have a status of COMPLETED only when all treatments have a status of COMPLETED.

TreatmentDescription

string

A custom description for the treatment.

TreatmentName

string

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

Version

integer

The campaign version number.

TreatmentResource

Attribute Type Description

Id

string

The unique treatment ID.

MessageConfiguration

MessageConfiguration

The message configuration settings.

Schedule

Schedule

The campaign schedule.

SizePercent

integer

The allocated percentage of users for this treatment.

State

CampaignState

The treatment status.

TreatmentDescription

string

A custom description for the treatment.

TreatmentName

string

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

CampaignState

Attribute Type Description

CampaignStatus

string

The status of the campaign, or the status of a treatment that belongs to an A/B test campaign.

Valid values: SCHEDULED, EXECUTING, PENDING_NEXT_RUN, COMPLETED, PAUSED

MessageBody

Attribute Type Description

Message

string

The error message returned from the API.

RequestID

string

The unique message body ID.