SparkPost logodev

Recipient Lists

Run in Postman
Import the SparkPost API as a Postman collection

A recipient list is a collection of recipients that can be used in a transmission. The Recipient List API provides the means to manage recipient lists. When creating a new transmission using the Transmissions API, the recipients may be submitted "inline" as part of the transmission data, or a stored recipient list id attribute can be specified.

The Recipient List API operates on lists as a whole and does not currently support management of individual recipients.

Recipient List Object

Example

{
  "results": {
    "id": "unique_id_4_graduate_students_list",
    "name": "graduate_students",
    "description": "An email list of graduate students at UMBC",
    "attributes": {
      "internal_id": 112,
      "list_group_id": 12321
    },
    "total_accepted_recipients": 3,
    "recipients": [ ... ]
  }
}

Attributes

id string

Unique alphanumeric ID.
Maximum length: 64 bytes

name string

Recipient list display name.
Maximum length: 64 bytes

description string

Description of the recipient list.
Maximum length: 1024 bytes

attributes object

An object of arbitrary metadata related to this list. This data is not used by the API. It is only for the user.

recipients array of objects

Array of recipient objects. See the Recipient Object.

Recipient Object

Recipients are described in an array of objects with the following attributes:

Example

{
  "address": {
    "email": "fred.jones@flintstone.com",
    "name": "Grad Student Office"
  },
  "tags": [
    "driver",
    "fred",
    "flintstone"
  ],
  "metadata": {
    "age": "33",
    "place": "NY"
  },
  "substitution_data": {
    "favorite_color": "Bright Green",
    "job": "Firefighter"
  }
}

Attributes

address object or string required

Address information for a recipient. See the Address Object.

return_path string

Email address to use for envelope FROM. Overrides transmission level return_path. The domain part of the return_path address must be a CNAME-verified sending domain. The local part of the return_path address will be overwritten by SparkPost.

For Enterprise accounts, the return_path may be any valid email address and the localpart in the return_path will not be overwritten by SparkPost.

tags array

Array of text labels associated with a recipient. Tags are available in Webhook events. Maximum number of tags - 10 per recipient, 100 system wide. Any tags over the limits are ignored.

metadata object

Key/value pairs associated with a recipient. Metadata is available during events through the Webhooks and is provided to the template engine. Recipient metadata takes precedence over transmission metadata when there are conflicts. The maximum length is 10KB per recipient.

substitution_data object

Key/value pairs associated with a recipient that are provided to the template engine. Recipient substitution data takes precedence over transmission substitution data. Unlike metadata, substitution data is not included in Webhook events. The maximum length is 100KB per recipient.

Address Object

If the address attribute is a string, it is interpreted as the email address. If it is an object, it is described with the following attributes:

Attributes

email string required

Valid email address

name string

Name attached to the email address

header_to string

Email address to display in the To header instead of address.email (for CC and BCC)

Constructing Headers using the Address Attributes

The address.email attribute is used as the envelope RCPT TO value.

If the address attribute is specified as a string instead of an address object, the address string is used as the envelope RCPT TO value.

The address.name attribute, in conjuction with the address.email attribute, is used to construct the content To header.

To: "address.name" <address.email>

If the address.name attribute is not specified, the To header uses the address.email attribute in contructing the header.

To: address.email

If the address is specified as a string instead of an address object, the To header is constructed using the address string.

To: address

If the address.header_to attribute is specified, then the To header uses the address.header_to attribute in constructing the header. address.header_to can be used to BCC (blind carbon copy) recipients, by hiding the envelope RCPT TO address and replacing it with an alternative address in the To header.

To: address.header_to

or:

To: "address.name" <address.header_to>

The To header is only constructed for messages built from email part content. The To header is not built for email_rfc822 content.

Request

POST /api/v1/recipient-lists?num_rcpt_errors=3
{
  "id": "unique_id_4_graduate_students_list",
  "name": "graduate_students",
  "description": "An email list of graduate students at UMBC",
  "attributes": {
    "internal_id": 112,
    "list_group_id": 12321
  },
  "recipients": [
    {
      "address": {
        "email": "wilmaflin@yahoo.com",
        "name": "Wilma"
      },
      "tags": [
        "greeting",
        "prehistoric",
        "fred",
        "flintstone"
      ],
      "metadata": {
        "age": "24",
        "place": "Bedrock"
      },
      "substitution_data": {
        "favorite_color": "SparkPost Orange",
        "job": "Software Engineer"
      }
    },
    {
      "address": {
        "email": "abc@flintstone.com",
        "name": "ABC"
      },
      "tags": [
        "driver",
        "flintstone"
      ],
      "metadata": {
        "age": "52",
        "place": "MD"
      },
      "substitution_data": {
        "favorite_color": "Sky Blue",
        "job": "Driver"
      }
    },
    {
      "address": {
        "email": "fred.jones@flintstone.com",
        "name": "Grad Student Office",
        "header_to": "grad-student-office@flintstone.com"
      },
      "tags": [
        "driver",
        "fred",
        "flintstone"
      ],
      "metadata": {
        "age": "33",
        "place": "NY"
      },
      "substitution_data": {
        "favorite_color": "Bright Green",
        "job": "Firefighter"
      }
    }
  ]
}

Response

{
  "results": {
    "total_rejected_recipients": 0,
    "total_accepted_recipients": 3,
    "id": "unique_id_4_graduate_students_list",
    "name": "graduate_students"
  }
}

{
  "errors": [
    {
      "message": "At least one valid recipient is required",
      "code": "5002"
    }
  ]
}

{
  "errors": [
    {
      "message": "List already exists",
      "code": "5001",
      "description": "List 'unique_id_4_graduate_students_list' already exists"
    }
  ]
}

{
  "errors": [
    {
      "message": "invalid data format/type",
      "code": "1300",
      "description": "List id 'rcptlist_id_students_list' cannot start with 'rcptlist_'"
    }
  ]
}

Create a Recipient List

POST/api/v1/recipient-lists{?num_rcpt_errors}

Parameters

num_rcpt_errors number

Maximum number of recipient errors that this call can return, otherwise all validation errors are returned.

Request Body

id string

Unique alphanumeric ID. If an id is not specified, one is generated.
Maximum length: 64 bytes

name string

Recipient list display name. If a name is not specified, it defaults to the same value as id.
Maximum length: 64 bytes

description string

Description of the recipient list.
Maximum length: 1024 bytes

attributes object

An object of arbitrary metadata related to this list.

recipients array of objects required

Array of recipient objects. See the Recipient Object.

At a minimum, the recipients array is required, which must contain a valid address. Use the num_rcpt_errors parameter to limit the number of recipient errors returned.

Request

GET /api/v1/recipient-lists/unique_id_4_graduate_students?show_recipients=true

Response

{
  "results": {
    "id": "unique_id_4_graduate_students_list",
    "name": "graduate_students",
    "description": "An email list of graduate students at UMBC",
    "attributes": {
      "internal_id": 112,
      "list_group_id": 12321
    },
    "total_accepted_recipients": 3,
    "recipients": [
      {
        "address": {
          "email": "wilmaflin@yahoo.com",
          "name": "Wilma"
        },
        "tags": [
          "greeting",
          "prehistoric",
          "fred",
          "flintstone"
        ],
        "metadata": {
          "age": "24",
          "place": "Bedrock"
        },
        "substitution_data": {
          "favorite_color": "SparkPost Orange",
          "job": "Software Engineer"
        }
      },
      {
        "address": {
          "email": "abc@flintstone.com",
          "name": "ABC"
        },
        "tags": [
          "driver",
          "flintstone"
        ],
        "metadata": {
          "age": "52",
          "place": "MD"
        },
        "substitution_data": {
          "favorite_color": "Sky Blue",
          "job": "Driver"
        }
      },
      {
        "address": {
          "email": "fred.jones@flintstone.com",
          "name": "Grad Student Office",
          "header_to": "grad-student-office@flintstone.com"
        },
        "tags": [
          "driver",
          "fred",
          "flintstone"
        ],
        "metadata": {
          "age": "33",
          "place": "NY"
        },
        "substitution_data": {
          "favorite_color": "Bright Green",
          "job": "Firefighter"
        }
      }
    ]
  }
}

{
  "errors": [
    {
      "message": "resource not found",
      "code": "1600",
      "description": "List 'unique_id_4_graduate_students_list' does not exist"
    }
  ]
}

Retrieve a Recipient List

GET/api/v1/recipient-lists/{id}{?show_recipients}

Parameters

id string required

Case sensitive.

show_recipients boolean

If true, return all the recipients contained in the list.

Retrieve details about a specified recipient list by specifying its id in the URI path. To retrieve the recipients contained in a list, the list must be specified and the show_recipients parameter must be set to true.

Request

PUT /api/v1/recipient-lists/unique_id_4_graduate_students_list?num_rcpt_errors=3
{
  "name": "updated_graduate_students",
  "description": "An email list of graduate students at UMBC",
  "attributes": {
    "internal_id": 112,
    "list_group_id": 12321
  },
  "recipients": [
    {
      "address": {
        "email": "wilmaflin@yahoo.com",
        "name": "Wilma"
      },
      "tags": [
        "greeting",
        "prehistoric",
        "fred",
        "flintstone"
      ],
      "metadata": {
        "age": "24",
        "place": "Bedrock"
      },
      "substitution_data": {
        "favorite_color": "SparkPost Orange",
        "job": "Software Engineer"
      }
    },
    {
      "address": {
        "email": "abc@flintstone.com",
        "name": "ABC"
      },
      "tags": [
        "driver",
        "flintstone"
      ],
      "metadata": {
        "age": "52",
        "place": "MD"
      },
      "substitution_data": {
        "favorite_color": "Sky Blue",
        "job": "Driver"
      }
    }
  ]
}

Response

{
  "results": {
    "total_rejected_recipients": 0,
    "total_accepted_recipients": 2,
    "id": "unique_id_4_graduate_students_list",
    "name": "updated_graduate_students"
  }
}

{
  "errors": [
    {
      "message": "invalid uri",
      "code": "1101",
      "description": "PUT requires a recipient list id in the URI"
    }
  ]
}

{
  "errors": [
    {
      "message": "At least one valid recipient is required",
      "code": "5002"
    }
  ]
}

{
  "errors": [
    {
      "message": "resource not found",
      "code": "1600",
      "description": "List 'unique_id_4_graduate_students_list' does not exist"
    }
  ]
}

{
  "errors": [
    {
      "message": "resource conflict",
      "code": "1602",
      "description": "List 'unique_id_4_graduate_students_list' is in use by msg generation"
    }
  ]
}

{
  "errors": [
    {
      "message": "resource conflict",
      "code": "1602",
      "description": "List 'unique_id_4_graduate_students_list' is in use by another request"
    }
  ]
}

{
  "errors": [
    {
      "message": "invalid data format/type",
      "code": "1300",
      "description": "List id 'unique_id_4_graduate_students_list' does not match the list being updated"
    }
  ]
}

Update a Recipient List

PUT/api/v1/recipient-lists/{id}{?num_rcpt_errors}

Parameters

id string required

Case sensitive.

num_rcpt_errors number

Maximum number of recipient errors that this call can return, otherwise all validation errors are returned.

If a recipients array is provided in the update request, it will replace the current recipients. This means that if you're adding, updating, or removing a single recipient, the recipients array must contain all current recipients, regardless they are being changed or not.

Request Body

name string

Recipient list display name.
Maximum length: 64 bytes

description string

Description of the recipient list.
Maximum length: 1024 bytes

attributes object

An object of arbitrary metadata related to this list. Specifying this will completely replace the current value.

recipients array of objects

Array of recipient objects. The new recipients will completely replace the existing recipients. See the Recipient Object.

Limitations

If a transmission using the recipient list has a state of "submitted" or "generating", the list cannot be updated. Also, if the transmission is scheduled and is within 10 minutes of the scheduled time, the list won't be updatable.

Returns

Returns the recipient list's name and id. If the recipients array was updated, it includes the number of accepted and rejected recipients.

Request

DELETE /api/v1/recipient-lists/unique_id_4_graduate_students_list

Response

{}

{
  "errors": [
    {
      "message": "invalid uri",
      "code": "1101",
      "description": "DELETE requires a recipient list id in the URI"
    }
  ]
}

{
  "errors": [
    {
      "message": "resource conflict",
      "code": "1602",
      "description": "List 'unique_id_4_graduate_students_list' is in use by msg generation"
    }
  ]
}

Delete a Recipient List

DELETE/api/v1/recipient-lists/{id}

Parameters

id string required

Case sensitive.

Request

GET /api/v1/recipient-lists

Response

{
  "results": [
    {
      "id": "unique_id_4_graduate_students_list",
      "name": "graduate_students",
      "description": "An email list of graduate students at UMBC",
      "attributes": {
        "internal_id": 112,
        "list_group_id": 12321
      },
      "total_accepted_recipients": 3
    },
    {
      "id": "unique_id_4_undergraduates",
      "name": "undergraduate_students",
      "description": "An email list of undergraduate students at UMBC",
      "attributes": {
        "internal_id": 111,
        "list_group_id": 11321
      },
      "total_accepted_recipients": 8
    }
  ]
}

List all Recipient Lists

GET/api/v1/recipient-lists

Returns an array of abbreviated recipient list objects. The recipients for each list are not included in the results. Retrieve a single list to get a list the recipients.