Monitoring Amazon SNS SMS activity - Amazon Simple Notification Service
Viewing delivery statisticsViewing CloudWatch metrics and logsViewing daily SMS usage reportsViewing monthly SMS usage reports

Monitoring Amazon SNS SMS activity

By monitoring your SMS activity, you can keep track of destination phone numbers, successful or failed deliveries, reasons for failure, costs, and other information. Amazon SNS helps by summarizing statistics in the console, sending information to Amazon CloudWatch, and sending daily SMS usage reports to an Amazon S3 bucket that you specify.

Viewing SMS delivery statistics

You can use the Amazon SNS console to view statistics about your recent SMS deliveries.

  1. Sign in to the Amazon SNS console.

  2. In the console menu, set the region selector to a region that supports SMS messaging.

  3. On the navigation panel, choose Text messaging (SMS).

  4. On the Mobile text messaging (SMS) page, in the Delivery statistics section, view the charts for your promotional and transactional SMS message deliveries. Each chart shows the following data for the preceding 15 days:

    • Promotional text message delivery rate

    • Transactional text message delivery rate

In the Text messaging preferences section, you can also choose the Edit button to go to the Amazon S3 bucket where you store your daily usage reports. For more information, see Viewing daily SMS usage reports from Amazon SNS.

Viewing Amazon CloudWatch metrics and logs for SMS deliveries

Use Amazon CloudWatch and Amazon CloudWatch Logs to monitor your SMS message deliveries.

Viewing Amazon CloudWatch metrics

Amazon SNS automatically collects metrics about your SMS message deliveries and pushes them to Amazon CloudWatch. You can use CloudWatch to monitor these metrics and create alarms to alert you when a metric crosses a threshold. For example, you can monitor CloudWatch metrics to learn your SMS delivery rate and your month-to-date SMS charges.

For information about monitoring CloudWatch metrics, setting CloudWatch alarms, and the types of metrics available, see Monitoring Amazon SNS topics using CloudWatch.

Viewing CloudWatch Logs

You can collect information about successful and unsuccessful SMS message deliveries by enabling Amazon SNS to write to Amazon CloudWatch Logs. For each SMS message that you send, Amazon SNS writes a log that includes the message price, the success or failure status, the reason for failure (if the message failed), the message dwell time, and other information.

To enable and view CloudWatch Logs for your SMS messages

  1. Sign in to the Amazon SNS console.

  2. In the console menu, set the region selector to a region that supports SMS messaging.

  3. On the navigation panel, choose Text messaging (SMS).

  4. On the Mobile text messaging (SMS) page, in the Text messaging preferences section, choose Edit.

  5. On the next page, expand the Delivery status logging section.

  6. For Success sample rate, specify the percentage of successful SMS deliveries for which Amazon SNS will write logs in CloudWatch Logs. For example:

    • To write logs only for failed deliveries, set this value to 0.

    • To write logs for 10% of your successful deliveries, set it to 10.

    If you don't specify a percentage, Amazon SNS writes logs for all successful deliveries.

  7. To provide the required permissions, do one of the following:

    • To create a new service role, choose Create new service role and then Create new roles. On the next page, choose Allow to give Amazon SNS write access to your account's resources.

    • To use an existing service role, choose Use existing service role and then paste the ARN name in the IAM role for successful and failed deliveries box.

      The service role you specify must allow write access to your account's resources. For more information on creating IAM roles, see Creating a role for an AWS service in the IAM User Guide.

  8. Choose Save changes.

  9. Back on the Mobile text messaging (SMS) page, go to the Delivery status logs section to view any available logs.

    Note

    Depending on the destination phone number's carrier, it can take up to 72 hours for delivery logs to appear in the Amazon SNS console.

Example log for successful SMS delivery

The delivery status log for a successful SMS delivery will resemble the following example:

{
    "notification": {
        "messageId": "34d9b400-c6dd-5444-820d-fbeb0f1f54cf",
        "timestamp": "2016-06-28 00:40:34.558"
    },
    "delivery": {
        "phoneCarrier": "My Phone Carrier",
        "mnc": 270,
        "numberOfMessageParts": 1,
        "destination": "+1XXX5550100",
        "priceInUSD": 0.00645,
        "smsType": "Transactional",
        "mcc": 310,
        "providerResponse": "Message has been accepted by phone carrier",
        "dwellTimeMs": 599,
        "dwellTimeMsUntilDeviceAck": 1344
    },
    "status": "SUCCESS"
}

Example log for failed SMS delivery

The delivery status log for a failed SMS delivery will resemble the following example:

{
    "notification": {
        "messageId": "1077257a-92f3-5ca3-bc97-6a915b310625",
        "timestamp": "2016-06-28 00:40:34.559"
    },
    "delivery": {
        "mnc": 0,
        "numberOfMessageParts": 1,
        "destination": "+1XXX5550100",
        "priceInUSD": 0.00645,
        "smsType": "Transactional",
        "mcc": 0,
        "providerResponse": "Unknown error attempting to reach phone",
        "dwellTimeMs": 1420,
        "dwellTimeMsUntilDeviceAck": 1692
    },
    "status": "FAILURE"
}

SMS delivery failure reasons

The reason for a failure is provided with the providerResponse attribute. SMS messages might fail to deliver for the following reasons:

  • Blocked as spam by phone carrier

  • Destination is on a blocked list

  • Invalid phone number

  • Message body is invalid

  • Phone carrier has blocked this message

  • Phone carrier is currently unreachable/unavailable

  • Phone has blocked SMS

  • Phone is on a blocked list

  • Phone is currently unreachable/unavailable

  • Phone number is opted out

  • This delivery would exceed max price

  • Unknown error attempting to reach phone

Viewing daily SMS usage reports from Amazon SNS

You can monitor your SMS deliveries by subscribing to daily usage reports from Amazon SNS. For each day that you send at least one SMS message, Amazon SNS delivers a usage report as a CSV file to the specified Amazon S3 bucket. It takes 24 hours for the SMS usage report to be available in the S3 bucket.

Daily usage report information

The usage report includes the following information for each SMS message that you send from your account.

Note that the report does not include messages that are sent to recipients who have opted out.

  • Time of publication for message (in UTC)

  • Message ID

  • Destination phone number

  • Message type

  • Delivery status

  • Message price (in USD)

  • Part number (a message is split into multiple parts if it is too long for a single message)

  • Total number of parts

Note

If Amazon SNS did not receive the part number, the value is set to zero.

Subscribing to daily usage reports

To subscribe to daily usage reports, you must create an Amazon S3 bucket with the appropriate permissions.

To create an Amazon S3 bucket for your daily usage reports

  1. From the AWS account that sends SMS messages, sign in to the Amazon S3 console.

  2. Choose Create Bucket.

  3. For Bucket Name, we recommend that you enter a name that is unique for your account and your organization. For example, use the pattern <my-bucket-prefix>-<account_id>-<org-id>.

    For information about conventions and restrictions for bucket names, see Rules for Bucket Naming in the Amazon Simple Storage Service User Guide.

  4. Choose Create.

  5. In the All Buckets table, choose the bucket.

  6. In the Permissions tab, choose Bucket policy.

  7. In the Bucket Policy Editor window, provide a policy that allows the Amazon SNS service principal to write to your bucket. For an example, see Example bucket policy.

    If you use the example policy, remember to replace amzn-s3-demo-bucket with the bucket name that you chose in Step 3.

  8. Choose Save.

To subscribe to daily usage reports

  1. Sign in to the Amazon SNS console.

  2. On the navigation panel, choose Text messaging (SMS).

  3. On the Text messaging (SMS) page, in the Text messaging preferences section, choose Edit.

    Text messaging preferences section

  4. On the Edit text messaging preferences page, in the Details section, specify the Amazon S3 bucket name for usage reports.

    Details section of the Edit text messaging preferences page

  5. Choose Save changes.

Example bucket policy

The following policy allows the Amazon SNS service principal to perform the s3:PutObject, s3:GetBucketLocation, and s3:ListBucket actions.

AWS provides tools for all services with service principals that have been given access to resources in your account. When the principal in an Amazon S3 bucket policy statement is an AWS service principal, you can use the aws:SourceArn or aws:SourceAccount global condition keys to protect against the confused deputy problem. To limit which region and account from which the bucket can receive daily usage reports, use aws:SourceArn as shown in the example below. If you do not wish to limit which regions can generate these reports, use aws:SourceAccount to limit based on which account is generating the reports. If you don't know the ARN of the resource, use aws:SourceAccount.

Use the following example that includes confused deputy protection when you create an Amazon S3 bucket to receive daily SMS usage reports from Amazon SNS.

{
	"Version": "2008-10-17",
	"Statement": [{
			"Sid": "AllowPutObject",
			"Effect": "Allow",
			"Principal": {
				"Service": "sns.amazonaws.com"
			},
			"Action": "s3:PutObject",
			"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
			"Condition": {
				"StringEquals": {
					"aws:SourceAccount": "account_id"
				},
				"ArnLike": {
					"aws:SourceArn": "arn:aws:sns:region:account_id:*"
				}
			}
		},
		{
			"Sid": "AllowGetBucketLocation",
			"Effect": "Allow",
			"Principal": {
				"Service": "sns.amazonaws.com"
			},
			"Action": "s3:GetBucketLocation",
			"Resource": "arn:aws:s3:::amzn-s3-demo-bucket",
			"Condition": {
				"StringEquals": {
					"aws:SourceAccount": "account_id"
				},
				"ArnLike": {
					"aws:SourceArn": "arn:aws:sns:region:account_id:*"
				}
			}
		},
		{
			"Sid": "AllowListBucket",
			"Effect": "Allow",
			"Principal": {
				"Service": "sns.amazonaws.com"
			},
			"Action": "s3:ListBucket",
			"Resource": "arn:aws:s3:::amzn-s3-demo-bucket",
			"Condition": {
				"StringEquals": {
					"aws:SourceAccount": "account_id"
				},
				"ArnLike": {
					"aws:SourceArn": "arn:aws:sns:region:account_id:*"
				}
			}
		}
	]
}
Note

You can publish usage reports to Amazon S3 buckets that are owned by the AWS account that's specified in the Condition element in the Amazon S3 policy. To publish usage reports to an Amazon S3 bucket that another AWS account owns, see How can I copy S3 objects from another AWS account?.

Example daily usage report

After you subscribe to daily usage reports, each day, Amazon SNS puts a CSV file with usage data in the following location:

<amzn-s3-demo-bucket>/SMSUsageReports/<region>/YYYY/MM/DD/00x.csv.gz

Each file can contain up to 50,000 records. If the records for a day exceed this quota, Amazon SNS will add multiple files.

The following shows an example report:

PublishTimeUTC,MessageId,DestinationPhoneNumber,MessageType,DeliveryStatus,PriceInUSD,PartNumber,TotalParts
2016-05-10T03:00:29.476Z,96a298ac-1458-4825-a7eb-7330e0720b72,1XXX5550100,Promotional,Message has been accepted by phone carrier,0.90084,0,1
2016-05-10T03:00:29.561Z,1e29d394-d7f4-4dc9-996e-26412032c344,1XXX5550100,Promotional,Message has been accepted by phone carrier,0.34322,0,1
2016-05-10T03:00:30.769Z,98ba941c-afc7-4c51-ba2c-56c6570a6c08,1XXX5550100,Transactional,Message has been accepted by phone carrier,0.27815,0,1

Viewing monthly SMS usage reports from Amazon SNS

Track your monthly SMS usage by country.

Monthly usage report information

The usage report includes the following information for each SMS message that you send from your account. The report doesn't include messages that are sent to recipients who have opted-out.

  • Monthly usage cost (in USD)

  • Number of SMS messages published as a request to Amazon SNS

  • Number of times Amazon SNS called AWS End User Messaging SMS

  • Cost incurred for delivering to each country

Viewing monthly usage reports

To view monthly usage reports

  1. Sign in to the AWS Management Console and open the AWS Billing console at https://console.aws.amazon.com/billing/.

  2. On the navigation panel, choose Cost Explorer.

  3. On the Report parameters panel, for the Service field, choose Pinpoint.

    Note

    If this is your first time accessing AWS Cost Management, you will receive the following message:

    Since this is your first visit, it will take some time to prepare your cost and usage data. Please check back in 24 hours.

  4. For the Usage type field, choose the unit type you want to measure.

    The Cost and Usage graph displays the output of your selections.

  5. (Optional) Choose Save report to library to .