Developer | MailChimp

Get a list of conversations

GET /conversations

Get a list of conversations for the account.

Query string parameters

fields	Type: Array	Title: Fields	Read only: false	A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
exclude_fields	Type: Array	Title: Exclude Fields	Read only: false	A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
count	Type: Integer	Title: Count	Read only: true	The number of records to return.
offset	Type: Integer	Title: Offset	Read only: false	The number of records from a collection to skip. Iterating over large collections with this parameter can be slow.
has_unread_messages	Type: String	Title: Has Unread Messages	Read only: false	Whether the conversation has any unread messages.
list_id	Type: String	Title: List ID	Read only: false	The unique id for the list.
campaign_id	Type: String	Title: Campaign ID	Read only: false	The unique id for the campaign.

Response body parameters

conversations

Type: Array

Title: Conversations

Read only: false

An list of conversations.

Show properties

Type: String

Title: ID

Read only: true

A string that uniquely identifies this conversation.

message_count

Type: Integer

Title: Message Count

Read only: true

The total number of messages in this conversation.

campaign_id

Type: String

Title: Campaign ID

Read only: true

The unique identifier of the campaign for this conversation.

list_id

Type: String

Title: List ID

Read only: true

The unique identifier of the list for this conversation.

unread_messages

Type: Integer

Title: Unread Messages

Read only: true

The number of unread messages in this conversation.

from_label

Type: String

Title: From Label

Read only: true

A label representing the sender of this message.

from_email

Type: String

Title: From Email

Read only: true

A label representing the email of the sender of this message.

subject

Type: String

Title: Subject

Read only: true

The subject of the message.

last_message

Type: Object

Title: Last Message

Read only: false

The most recent message in the conversation.

Show properties

from_label	Type: String	Title: From Label	Read only: true	A label representing the sender of this message.
from_email	Type: String	Title: From Email	Read only: true	A label representing the email of the sender of this message.
subject	Type: String	Title: Subject	Read only: true	The subject of this message.
message	Type: String	Title: Message	Read only: true	The plain-text content of the message.
read	Type: Boolean	Title: Read	Read only: false	Whether this message has been marked as read.
timestamp	Type: String	Title: Timestamp	Read only: true	The date and time the message was either sent or received.

_links

Type: Array

Title: Links

Read only: true

A list of link types and descriptions for the API schema documents.

Show properties

rel	Type: String	Title: Rel	Read only: true	As with an HTML ‘rel’ attribute, this describes the type of link.
href	Type: String	Title: Href	Read only: true	This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
method	Type: String	Title: Method	Read only: true	The HTTP method that should be used when accessing the URL defined in ‘href’. Possible Values: GET POST PUT PATCH DELETE OPTIONS HEAD
targetSchema	Type: String	Title: Target Schema	Read only: true	For GETs, this is a URL representing the schema that the response should conform to.
schema	Type: String	Title: Schema	Read only: true	For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.

total_items

Type: Integer

Title: Item Count

Read only: false

The total number of items matching the query regardless of pagination.

_links

Type: Array

Title: Links

Read only: true

A list of link types and descriptions for the API schema documents.

Show properties

rel	Type: String	Title: Rel	Read only: true	As with an HTML ‘rel’ attribute, this describes the type of link.
href	Type: String	Title: Href	Read only: true	This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
method	Type: String	Title: Method	Read only: true	The HTTP method that should be used when accessing the URL defined in ‘href’. Possible Values: GET POST PUT PATCH DELETE OPTIONS HEAD
targetSchema	Type: String	Title: Target Schema	Read only: true	For GETs, this is a URL representing the schema that the response should conform to.
schema	Type: String	Title: Schema	Read only: true	For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.

Example request


curl --request GET \
--url 'https://usX.api.mailchimp.com/3.0/conversations' \
--user 'anystring:apikey' \
--include

Example response


HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8
Content-Length: 7119
Vary: Accept-Encoding
X-Request-Id: 247cc074-5728-49d5-b837-9970fc68d5ca
Link: <https://api.mailchimp.com/schema/3.0/Conversations/Collection.json>; rel="describedBy"
Date: Tue, 15 Sep 2015 19:19:45 GMT
Connection: keep-alive


{
  "conversations": [
    {
      "id": "fa8c387539",
      "message_count": 1,
      "campaign_id": "42694e9e57",
      "list_id": "57afe96172",
      "unread_messages": 0,
      "from_label": "Freddie Jokes ([email protected])",
      "from_email": "[email protected]",
      "subject": "Re: I have a rice crispy treat watermelon farm.",
      "last_message": {
        "from_label": "[email protected]",
        "from_email": "[email protected]",
        "subject": "Re: I have a rice crispy treat watermelon farm.",
        "message": "We&#39;re so glad you like it! Stay tuned for his next joke coming Monday.",
        "read": true,
        "timestamp": "2015-09-15 19:17:59"
      },
      "_links": [
        {
          "rel": "self",
          "href": "https://usX.api.mailchimp.com/3.0/conversations/fa8c387539",
          "method": "GET",
          "targetSchema": "https://api.mailchimp.com/schema/3.0/Conversations/Instance.json"
        },
        {
          "rel": "parent",
          "href": "https://usX.api.mailchimp.com/3.0/conversations",
          "method": "GET",
          "targetSchema": "https://api.mailchimp.com/schema/3.0/Conversations/Collection.json",
          "schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Conversations.json"
        },
        {
          "rel": "messages",
          "href": "https://usX.api.mailchimp.com/3.0/conversations/fa8c387539/messages",
          "method": "GET",
          "targetSchema": "https://api.mailchimp.com/schema/3.0/Conversations/Messages/Collection.json",
          "schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Conversations/Messages.json"
        },
        {
          "rel": "campaign",
          "href": "https://usX.api.mailchimp.com/3.0/campaigns/42694e9e57",
          "method": "GET",
          "targetSchema": "https://api.mailchimp.com/schema/3.0/Campaigns/Instance.json"
        },
        {
          "rel": "list",
          "href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172",
          "method": "GET",
          "targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Instance.json"
        }
      ]
    }
  ],
  "total_items": 1,
  "_links": [
    {
      "rel": "self",
      "href": "https://usX.api.mailchimp.com/3.0/conversations",
      "method": "GET",
      "targetSchema": "https://api.mailchimp.com/schema/3.0/Conversations/Collection.json",
      "schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Conversations.json"
    },
    {
      "rel": "parent",
      "href": "https://usX.api.mailchimp.com/3.0/",
      "method": "GET",
      "targetSchema": "https://api.mailchimp.com/schema/3.0/Root.json"
    }
  ]
}

Error response

type	Type: String	Title: Problem Type	Read only: false	An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
title	Type: String	Title: Error Title	Read only: false	A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
status	Type: Integer	Title: HTTP Status Code	Read only: false	The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
detail	Type: String	Title: Error Message	Read only: false	A human-readable explanation specific to this occurrence of the problem. Learn more about errors.
instance	Type: String	Title: Instance ID	Read only: false	A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.

Get information about a conversation

GET /conversations/{conversation_id}

Get details about an individual conversation.

Path parameters

conversation_id

The unique id for the conversation.

Query string parameters

fields	Type: Array	Title: Fields	Read only: false	A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
exclude_fields	Type: Array	Title: Exclude Fields	Read only: false	A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.

Response body parameters

Type: String

Title: ID

Read only: true

A string that uniquely identifies this conversation.

message_count

Type: Integer

Title: Message Count

Read only: true

The total number of messages in this conversation.

campaign_id

Type: String

Title: Campaign ID

Read only: true

The unique identifier of the campaign for this conversation.

list_id

Type: String

Title: List ID

Read only: true

The unique identifier of the list for this conversation.

unread_messages

Type: Integer

Title: Unread Messages

Read only: true

The number of unread messages in this conversation.

from_label

Type: String

Title: From Label

Read only: true

A label representing the sender of this message.

from_email

Type: String

Title: From Email

Read only: true

A label representing the email of the sender of this message.

subject

Type: String

Title: Subject

Read only: true

The subject of the message.

last_message

Type: Object

Title: Last Message

Read only: false

The most recent message in the conversation.

Show properties

from_label	Type: String	Title: From Label	Read only: true	A label representing the sender of this message.
from_email	Type: String	Title: From Email	Read only: true	A label representing the email of the sender of this message.
subject	Type: String	Title: Subject	Read only: true	The subject of this message.
message	Type: String	Title: Message	Read only: true	The plain-text content of the message.
read	Type: Boolean	Title: Read	Read only: false	Whether this message has been marked as read.
timestamp	Type: String	Title: Timestamp	Read only: true	The date and time the message was either sent or received.

_links

Type: Array

Title: Links

Read only: true

A list of link types and descriptions for the API schema documents.

Show properties

rel	Type: String	Title: Rel	Read only: true	As with an HTML ‘rel’ attribute, this describes the type of link.
href	Type: String	Title: Href	Read only: true	This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
method	Type: String	Title: Method	Read only: true	The HTTP method that should be used when accessing the URL defined in ‘href’. Possible Values: GET POST PUT PATCH DELETE OPTIONS HEAD
targetSchema	Type: String	Title: Target Schema	Read only: true	For GETs, this is a URL representing the schema that the response should conform to.
schema	Type: String	Title: Schema	Read only: true	For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.

Example request


curl --request GET \
--url 'https://usX.api.mailchimp.com/3.0/conversations/fa8c387539' \
--user 'anystring:apikey' \
--include

Example response


HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8
Content-Length: 1662
Vary: Accept-Encoding
X-Request-Id: ca32c78d-28e2-42c7-80c3-140a81401e3a
Link: <https://api.mailchimp.com/schema/3.0/Conversations/Instance.json>; rel="describedBy"
Date: Tue, 15 Sep 2015 19:25:46 GMT
Connection: keep-alive


{
  "id": "fa8c387539",
  "message_count": 1,
  "campaign_id": "42694e9e57",
  "list_id": "57afe96172",
  "unread_messages": 0,
  "from_label": "Freddie Jokes ([email protected])",
  "from_email": "[email protected]",
  "subject": "Re: I have a rice crispy treat watermelon farm.",
  "last_message": {
    "from_label": "[email protected]",
    "from_email": "[email protected]",
    "subject": "Re: I have a rice crispy treat watermelon farm.",
    "message": "We&#39;re so glad you like it! Stay tuned for his next joke coming Monday.",
    "read": true,
    "timestamp": "2015-09-15 19:17:59"
  },
  "_links": [
    {
      "rel": "self",
      "href": "https://usX.api.mailchimp.com/3.0/conversations/fa8c387539",
      "method": "GET",
      "targetSchema": "https://api.mailchimp.com/schema/3.0/Conversations/Instance.json"
    },
    {
      "rel": "parent",
      "href": "https://usX.api.mailchimp.com/3.0/conversations",
      "method": "GET",
      "targetSchema": "https://api.mailchimp.com/schema/3.0/Conversations/Collection.json",
      "schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Conversations.json"
    },
    {
      "rel": "messages",
      "href": "https://usX.api.mailchimp.com/3.0/conversations/fa8c387539/messages",
      "method": "GET",
      "targetSchema": "https://api.mailchimp.com/schema/3.0/Conversations/Messages/Collection.json",
      "schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Conversations/Messages.json"
    },
    {
      "rel": "campaign",
      "href": "https://usX.api.mailchimp.com/3.0/campaigns/42694e9e57",
      "method": "GET",
      "targetSchema": "https://api.mailchimp.com/schema/3.0/Campaigns/Instance.json"
    },
    {
      "rel": "list",
      "href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172",
      "method": "GET",
      "targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Instance.json"
    }
  ]
}

Error response

type	Type: String	Title: Problem Type	Read only: false	An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
title	Type: String	Title: Error Title	Read only: false	A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
status	Type: Integer	Title: HTTP Status Code	Read only: false	The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
detail	Type: String	Title: Error Message	Read only: false	A human-readable explanation specific to this occurrence of the problem. Learn more about errors.
instance	Type: String	Title: Instance ID	Read only: false	A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.

Conversations

Subresources

Available methods

Get a list of conversations

GET /conversations

Query string parameters

Response body parameters

Possible Values:

Possible Values:

Example request

Example response

Error response

Get information about a conversation

GET /conversations/{conversation_id}

Path parameters

Query string parameters

Response body parameters

Possible Values:

Example request

Example response

Error response