/messages/sms/{sms_id}/recipients

Secured By: Authentication Token
Description:

Use this resource to view the list of recipients for a given message. In this case, all detail on a recipient is given in the list output.

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.

Status

Headers

Name Type Description
Link string

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

Example

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

Body

Format: application/json

Example
[
  {
    "formatted_phone": "+16515551000",
    "phone": "6515551000",
    "status": "sent",
    "created_at": null,
    "sent_at": "2014-10-25T16:08:12Z",
    "completed_at": "2014-10-25T16:08:14Z",
    "_links": {
      "sms_message": "/messages/sms/4",
      "self": "/messages/sms/4/recipients/42"
    }
  },
  {
    "formatted_phone": "+16515555555",
    "phone": "6515555555",
    "status": "sent",
    "created_at": null,
    "sent_at": "2014-10-25T16:08:15Z",
    "completed_at": "2014-10-25T16:08:17Z",
    "_links": {
      "sms_message": "/messages/sms/4",
      "self": "/messages/sms/4/recipients/43"
    }
  }
]
Schema
Array of objects that may include:
Name Type Description
phone string

The phone number provided in the initial API call.

Example

6515551000
formatted_phone string

The phone number converted to E.164 format. This is the value passed to the SMS provider.

Example

+16515551000
status string

The status of the message send to the recipient.

  • 'new' - The recipient has not been sent.
  • 'sending' - The recipient has been sent, but no delivery information has been obtained.
  • 'sent' - The recipient has been confirmed as sent.
  • 'failed' - The recipient has been confirmed as failed.
  • 'blacklisted' - The recipient is on the blacklist (not yet implemented for Email).

Valid Values:

  • new
  • sending
  • sent
  • failed
  • blacklisted

error_message string

When a recipient has a status of 'failed', this will be the reason that the SMS provider rejected the recipient.

created_at string

The date and time when the recipient was created.

Example

2013-03-15T21:10:30Z
completed_at string

The date and time that the recipient entered a final state (sent|failed|blacklisted).

Example

2013-03-15T21:11:02Z
_links object

Link relations available for the SMS Recipient.

Example

{
  "self": "/messages/sms/10507/recipients/364898",
  "sms_message": "/messages/sms/10507"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "SMS Recipients",
  "description": "A list of recipients of an sms message",
  "type": "array",
  "items": {
    "title": "SMS Recipient",
    "description": "Get information about an sms recipient",
    "properties": {
      "phone": {
        "description": "The phone number provided in the initial API call.",
        "type": "string",
        "example": "6515551000"
      },
      "formatted_phone": {
        "description": "The phone number converted to E.164 format.  This is the value passed to the SMS provider. ",
        "type": "string",
        "example": "+16515551000"
      },
      "status": {
        "description": "The status of the message send to the recipient.\n\n- 'new' - The recipient has not been sent.\n- 'sending' - The recipient has been sent, but no delivery information has been obtained.\n- 'sent' - The recipient has been confirmed as sent.\n- 'failed' - The recipient has been confirmed as failed.\n- 'blacklisted' - The recipient is on the blacklist (not yet implemented for Email).",
        "type": "string",
        "enum": [
          "new",
          "sending",
          "sent",
          "failed",
          "blacklisted"
        ]
      },
      "error_message": {
        "description": "When a recipient has a status of 'failed', this will be the reason that the SMS provider rejected the recipient.",
        "type": "string"
      },
      "created_at": {
        "description": "The date and time when the recipient was created. ",
        "type": "string",
        "example": "2013-03-15T21:10:30Z"
      },
      "completed_at": {
        "description": "The date and time that the recipient entered a final state (sent|failed|blacklisted). ",
        "type": "string",
        "example": "2013-03-15T21:11:02Z"
      },
      "_links": {
        "description": "Link relations available for the SMS Recipient.",
        "type": "object",
        "example": "{\n\"self\": \"/messages/sms/10507/recipients/364898\",\n\"sms_message\": \"/messages/sms/10507\"\n}"
      }
    }
  }
}
Description

Large recipient lists may be saved asynchronously; this response means the recipient list is still being processed after a message create, so you might wait a few seconds and try again.

Body

Format: application/json

Example
{
  "message": "Recipient list is being built and is not yet complete"
}

Body

Format: application/json

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