/messages/sms

Use this resource to list and create SMS messages.

Secured By: Authentication Token
Description:

List SMS messages.

Responses with more than 50 records will be paginated to 50 records per response, unless otherwise specified.

Headers

Name Required Type Description
X-AUTH-TOKEN * string

An authentication token provided to you by GovDelivery.

Query Parameters

Name Required Type Description
page_size integer

Limit number of messages returned with each request.

Minimum Value: 1

Maximum Value: 100

Example

messages/sms?page_size=5
sort_by string

Field by which to sort results.

Default Value: created_at

Example

messages/sms?sort_by=created_at
sort_order string

Order by which to sort results.

Default Value: DESC

Valid Values:

  • ASC
  • DESC

Example

messages/sms?sort_order=ASC

Status

Headers

Name Type Description
Link string

Appropriate pagination link relations. Can include “first”, “last”, “prev”, and “next” relations.

Example

< /messages/sms?page=1>; rel="first",
< /messages/sms?page=2>; rel="prev",
< /messages/sms?page=4>; rel="next",
< /messages/sms?page=5>; rel="last"

Body

Format: application/json

Example
[
  {
    "id": 4,
    "body": "Test Message!",
    "created_at": "2012-10-30T16:26:19Z",
    "status": "completed",
    "_links": {
      "self": "/messages/sms/4",
      "recipients": "/messages/sms/4/recipients",
      "failed": "/messages/sms/4/recipients/failed",
      "sent": "/messages/sms/4/recipients/sent"
    }
  },
  {
    "id": 165532,
    "body": "Today is Sunny and 70F",
    "created_at": "2014-10-07T17:27:12Z",
    "status": "completed",
    "_links": {
      "self": "/messages/sms/165532",
      "recipients": "/messages/sms/165532/recipients",
      "failed": "/messages/sms/165532/recipients/failed",
      "sent": "/messages/sms/165532/recipients/sent"
    }
  }
]
Schema
Array of objects that may include:
Name Type Description
body string

The message body

Example

Today is Sunny and 70F.
created_at string

The date and time when the message was created.

Example

2013-01-30T17:45:27Z
_links object

An object that defines links to related objects.

Properties

{
  "self": {
    "description": "Relative URI of the object",
    "type": "string",
    "example": "/messages/sms/10040"
  },
  "recipients": {
    "description": "Relative URI to the list of recipients of the message",
    "type": "string",
    "example": "/messages/sms/10040/recipients"
  },
  "failed": {
    "description": "Relative URI to the list of recipients that have failed to receive the message",
    "type": "string",
    "example": "/messages/sms/10040/recipients/failed"
  },
  "sent": {
    "description": "Relative URI to the list of recipients that have been successfully received the message",
    "type": "string",
    "example": "/messages/sms/10040/recipients/sent"
  }
}
status string

new - message has been created

queued - message has been queued for sending

sending - message has begun sending

completed - all recipients have positive confirmation or have expired

Valid Values:

  • new
  • queued
  • sending
  • completed

Example

completed
 
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "SMS Messages",
  "description": "A List of sms messageses you have sent.",
  "type": "array",
  "items": {
    "title": "SMS Message",
    "type": "object",
    "properties": {
      "body": {
        "description": "The message body",
        "type": "string",
        "example": "Today is Sunny and 70F."
      },
      "created_at": {
        "description": "The date and time when the message was created.",
        "type": "string",
        "example": "2013-01-30T17:45:27Z"
      },
      "_links": {
        "title": "Relational Links",
        "description": "An object that defines links to related objects.",
        "type": "object",
        "properties": {
          "self": {
            "description": "Relative URI of the object",
            "type": "string",
            "example": "/messages/sms/10040"
          },
          "recipients": {
            "description": "Relative URI to the list of recipients of the message",
            "type": "string",
            "example": "/messages/sms/10040/recipients"
          },
          "failed": {
            "description": "Relative URI to the list of recipients that have failed to receive the message",
            "type": "string",
            "example": "/messages/sms/10040/recipients/failed"
          },
          "sent": {
            "description": "Relative URI to the list of recipients that have been successfully received the message",
            "type": "string",
            "example": "/messages/sms/10040/recipients/sent"
          }
        }
      },
      "status": {
        "description": "new - message has been created\n\nqueued - message has been queued for sending\n\nsending - message has begun sending\n\ncompleted - all recipients have positive confirmation or have expired",
        "type": "string",
        "enum": [
          "new",
          "queued",
          "sending",
          "completed"
        ],
        "example": "completed"
      }
    }
  }
}

Body

Format: application/json

Example
{
  "error": "Invalid authentication token"
}
Secured By: Authentication Token
Description:

Creates a new SMS message.

Headers

Name Required Type Description
X-AUTH-TOKEN * string

An authentication token provided to you by GovDelivery.

Body

Format: application/x-www-form-urlencoded

Form Parameters
Name Required Type Description
body * string

Body of the SMS.

Example

Today is Sunny and 70F.
recipients * string

List of objects defining who will receive the SMS. Objects must include a “phone” attribute.

Example

[
    {
      "phone": "6515551000"
    },
    {
      "phone": "(651) 555-1001"
    }
]
_links string

The links to be associated with this email message.

Possible Parameters are:

  • sms_template:
    • Required: No
    • UUID of a template to use. For more information on templates, see documentation for the /templates/email endpoint.

Example

{
  "sms_template": "new_template-1"
}
Example
{
  "body": "Today is Sunny and 70F",
  "recipients": [
    {
      "phone": "6515551000"
    },
    {
      "phone": "(651) 555-1001"
    }
  ],
  "_links": {
    "email_template": "new_template-10"
  }
}
Schema
Object that may include:
Name Required Type Description
body * string

Body of the SMS.

Example

Today is Sunny and 70F.
recipients * string

List of objects defining who will receive the SMS. Objects must include a “phone” attribute.

Example

[
    {
      "phone": "6515551000"
    },
    {
      "phone": "(651) 555-1001"
    }
]
_links string

The links to be associated with this email message.

Possible Parameters are:

  • sms_template:
    • Required: No
    • UUID of a template to use. For more information on templates, see documentation for the /templates/email endpoint.

Example

{
  "sms_template": "new_template-1"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "/messages/sms",
  "description": "Creates a new SMS message.",
  "type": "object",
  "properties": {
    "body": {
      "description": "Body of the SMS.",
      "type": "string",
      "maxLength": 160,
      "example": "Today is Sunny and 70F."
    },
    "recipients": {
      "description": "List of objects defining who will receive the SMS. Objects\nmust include a \"phone\" attribute.\n",
      "type": "string",
      "example": "[\n    {\n      \"phone\": \"6515551000\"\n    },\n    {\n      \"phone\": \"(651) 555-1001\"\n    }\n]\n"
    },
    "_links": {
      "description": "The links to be associated with this email message.\n\nPossible Parameters are:\n\n  - sms_template:\n    - Required: No\n    - UUID of a template to use. For more information on\n      templates, see documentation for the\n      [/templates/email](/api/tms/resource/templates/email/)\n      endpoint.\n",
      "type": "string",
      "example": "{\n  \"sms_template\": \"new_template-1\"\n}\n"
    }
  },
  "required": [
    "body",
    "recipients"
  ]
}

Status

Body

Format: application/json

Example
{
  "body": "Today is Sunny and 70F",
  "created_at": "2014-10-07T17:27:12Z",
  "completed_at": "2014-10-07T17:27:15Z",
  "status": "completed",
  "_links": {
    "self": "/messages/sms/165532",
    "recipients": "/messages/sms/165532/recipients",
    "failed": "/messages/sms/165532/recipients/failed",
    "sent": "/messages/sms/165532/recipients/sent"
  },
  "recipient_counts": {
    "total": 2,
    "new": 0,
    "sending": 0,
    "inconclusive": 0,
    "blacklisted": 0,
    "canceled": 0,
    "sent": 2,
    "failed": 0
  }
}
Description

Unprocessable Entity

Body

Format: application/json

Example
{
  "body":"",
  "created_at":null,
  "errors":{
    "body":[
      "can't be blank"
    ]
  }
}

Body

Format: application/json

Example
{
  "error": "Invalid authentication token"
}