/messages/email/{email_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/email/{email_id}/recipients?page=1>; rel="first",
< /messages/email/{email_id}/recipients?page=2>; rel="prev",
< /messages/email/{email_id}/recipients?page=4>; rel="next",
< /messages/email/{email_id}/recipients?page=5>; rel="last"

Body

Format: application/json

Example
[
  {
    "email": "test01@test.govdelivery.com",
    "macros": {
    },
    "status": "sent",
    "created_at": "2013-03-15T21:10:30Z",
    "completed_at": "2013-03-15T21:11:02Z",
    "_links": {
      "self": "/messages/email/10507/recipients/364897",
      "email_message": "/messages/email/10507",
      "opens": "/messages/email/10507/recipients/364897/opens",
      "clicks": "/messages/email/10507/recipients/364897/clicks"
    }
  },
  {
    "email": "test02@test.govdelivery.com",
    "macros": {
      "city": "RECIPIENT Saint Paul",
      "address": "RECIPIENT 408 Saint Peter Street",
      "company": "RECIPIENT GovDelivery",
      "url": "RECIPIENT www.govdelivery.com"
    },
    "status": "sent",
    "created_at": "2013-03-15T21:10:30Z",
    "completed_at": "2013-03-15T21:10:32Z",
    "_links": {
      "self": "/messages/email/10507/recipients/364898",
      "email_message": "/messages/email/10507",
      "opens": "/messages/email/10507/recipients/364898/opens",
      "clicks": "/messages/email/10507/recipients/364898/clicks"
    }
  }
]
Schema
Array of objects that may include:
Name Type Description
email string

The email address provided in the initial API call.

Example

test01@test.govdelivery.com
macros object

List of macros with values used for the recipient

Example

{
  "city": "RECIPIENT Saint Paul",
  "address": "RECIPIENT 408 Saint Peter Street",
  "company": "RECIPIENT GovDelivery",
  "url": "RECIPIENT www.govdelivery.com"
}
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 email 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 Email Recipient.

Example

{
  "self": "/messages/email/10507/recipients/364898",
  "email_message": "/messages/email/10507",
  "opens": "/messages/email/10507/recipients/364898/opens",
  "clicks": "/messages/email/10507/recipients/364898/clicks"
}
 
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Email Recipients",
  "description": "A list of recipients of an email message",
  "type": "array",
  "items": {
    "title": "Email Recipient",
    "description": "Get information about an email recipient",
    "properties": {
      "email": {
        "description": "The email address provided in the initial API call.",
        "type": "string",
        "example": "test01@test.govdelivery.com"
      },
      "macros": {
        "description": "List of macros with values used for the recipient",
        "type": "object",
        "example": "{\"city\":\"RECIPIENT Saint Paul\",\"address\":\"RECIPIENT 408 Saint Peter Street\",\"company\":\"RECIPIENT GovDelivery\",\"url\":\"RECIPIENT www.govdelivery.com\"}"
      },
      "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 email 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 Email Recipient.",
        "type": "object",
        "example": "{\n\"self\": \"/messages/email/10507/recipients/364898\",\n\"email_message\": \"/messages/email/10507\",\n\"opens\": \"/messages/email/10507/recipients/364898/opens\",\n\"clicks\": \"/messages/email/10507/recipients/364898/clicks\"\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"
}