Amazon Simple Notification Service
Developer Guide

Amazon SNS Message Attributes

Amazon SNS supports delivery of message attributes which let you provide structured metadata items (such as timestamps, geospatial data, signatures, and identifiers) about the message. Each message can have up to 10 attributes.

Message attributes are optional and separate from—but are sent together with—the message body. The receiver can use this information to decide how to handle the message without having to process the message body first.

For information about sending messages with attributes using the AWS Management Console or the AWS SDK for Java, see the Publishing a Message with Attributes to an Amazon SNS Topic tutorial.

Important

To use message attributes with Amazon SQS endpoints, you must set subscription attribute Raw Message Delivery to True. For more information about raw message delivery, see Amazon SNS Large Payload and Raw Message Delivery.

Message attributes are sent only when the message structure is String, not JSON.

You can also use message attributes to help structure the push notification message for mobile endpoints. In this scenario, the message attributes are used only to help structure the push notification message. The attributes are not delivered to the endpoint as they are when sending messages with message attributes to Amazon SQS endpoints.

You can also use message attributes to make your messages filterable using subscription filter policies. You can apply filter policies to topic subscriptions. When a filter policy is applied, a subscription receives only those messages that have attributes that the policy accepts. For more information, see Message Filtering.

Message Attribute Items and Validation

Each message attribute consists of the following items:

  • Name – The message attribute name can contain the following characters: A-Z, a-z, 0-9, underscore(_), hyphen(-), and period (.). The name must not start or end with a period, and it should not have successive periods. The name is case-sensitive and must be unique among all attribute names for the message. The name can be up to 256 characters long. The name cannot start with "AWS." or "Amazon." (or any variations in casing) because these prefixes are reserved for use by Amazon Web Services.

  • Type – The supported message attribute data types are String, String.Array, Number, and Binary. The data type has the same restrictions on the content as the message body. The data type is case-sensitive, and it can be up to 256 bytes long. For more information, see the Message Attribute Data Types and Validation section.

  • Value – The user-specified message attribute value. For string data types, the value attribute has the same restrictions on the content as the message body. For more information, see the Publish action in the Amazon Simple Notification Service API Reference.

Name, type, and value must not be empty or null. In addition, the message body should not be empty or null. All parts of the message attribute, including name, type, and value, are included in the message size restriction, which is 256 KB.

Message Attribute Data Types and Validation

Message attribute data types identify how the message attribute values are handled by Amazon SNS. For example, if the type is a number, Amazon SNS validates that it's a number.

Amazon SNS supports the following logical data types:

  • String – Strings are Unicode with UTF-8 binary encoding. For a list of code values, see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters.

  • String.Array – An array, formatted as a string, that can contain multiple values. The values can be strings, numbers, or the keywords true, false, and null.

  • Number – Numbers are positive or negative integers or floating-point numbers. Numbers have sufficient range and precision to encompass most of the possible values that integers, floats, and doubles typically support. A number can have a value from -109 to 109, with 5 digits of accuracy after the decimal point. Leading and trailing zeroes are trimmed.

  • Binary – Binary type attributes can store any binary data; for example, compressed data, encrypted data, or images.

Reserved Message Attributes for Mobile Push Notifications

The following table lists the reserved message attributes for mobile push notification services that you can use to structure your push notification message:

Push Notification Service Reserved Message Attribute Required Allowed Values

Baidu

AWS.SNS.MOBILE.BAIDU.DeployStatus

False
  • 1 (development environment; default)

  • 2 (production environment)

AWS.SNS.MOBILE.BAIDU.MessageType False
  • 0 (in-app message)

  • 1 (alert notification; default)

AWS.SNS.MOBILE.BAIDU.MessageKey False A short message identifier

MPNS

AWS.SNS.MOBILE.MPNS.Type

True
  • raw

  • toast

  • token (for tile notifications)

AWS.SNS.MOBILE.MPNS.NotificationClass True
  • priority

  • real time

  • regular

WNS

AWS.SNS.MOBILE.WNS.Type True Same as X-WNS-Type
AWS.SNS.MOBILE.WNS.CachePolicy False Same as X-WNS-Cache-Policy
AWS.SNS.MOBILE.WNS.Group False Same as X-WNS-Group
AWS.SNS.MOBILE.WNS.Match False Same as X-WNS-Match
AWS.SNS.MOBILE.WNS.SuppressPopup False Same as X-WNS-SuppressPopup
AWS.SNS.MOBILE.WNS.Tag False Same as X-WNS-Tag