Get all forwards by conversation

get/v1/conversations/{id}/forwards

Requires any one of these rolesAbout roles

org.permission.draft.read

Legacyorg.user.draft.read

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Retrieves all forwarded conversations based on the unique conversation ID.

To learn more, see Forwarding conversations in the Kustomer Help Center.

About this resource

Conversation forwards

A forward sends a copy of an entire conversation by email to someone outside it, such as a vendor, a warehouse or another department. It starts as a draft and is sent when you give it a send time.

Agents forward a conversation from the agent desktop when someone who isn't on the thread needs the full history, for example a shipping partner who has to investigate a lost package. A forward belongs to one conversation and its customer, and it emails all of that conversation's messages to the addresses you choose. Forwards are listed on the conversation they came from.

Lifecycle

A forward works like a draft: you create it, adjust it, and then send it.

`status`	Meaning
`draft`	Created without `sendAt`. Nothing has been sent, and you can still edit it.
`scheduled`	Has a `sendAt` and is waiting to go out.
`sent`	Sent.
`failed`	Sending failed.

Include sendAt when you create the forward to send it, or create it without one and set sendAt later with PUT /v1/forwards/{id}. Kustomer validates the email fields when a forward is scheduled.

Key fields

channel is always email. to is a list of { email, name } recipients and from is the { email, name } sender, which should be one of your org's email accounts; GET /v1/outboundAccounts lists them. app picks the sending integration (gmail or postmark). subject, body and replyTo work as they do for an email draft; body is the text you add for the recipient. attachments adds files that you upload through the forward attachment endpoints.

Which endpoint to use

To	Call
Forward a conversation by email	`POST /v1/conversations/{id}/forwards`
See every forward made from a conversation	`GET /v1/conversations/{id}/forwards`

To read, edit or schedule a single forward after creating it, use GET and PUT /v1/forwards/{id}. Creating a forward needs the conversation-forward permission (org.permission.conversation_forward.create), and listing forwards needs draft read access.

Path parameters

idstringrequired

Conversation ID.

Example "5faaf4a6ea0cb48cd0801bbf"

Responses

objectrequired

array<object>required

objectrequired

Open in the API console

curl --request GET \
  --url 'https://api.kustomerapp.com/v1/conversations/5faaf4a6ea0cb48cd0801bbf/forwards' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"

{
  "meta": {
    "pageSize": 100,
    "page": 1
  },
  "data": [
    {
      "id": "58210c6c2a8b9910002f6730",
      "type": "forward",
      "attributes": {
        "app": "postmark",
        "channel": "email",
        "from": {
          "name": "Sales",
          "email": "sales@example.com"
        },
        "to": [
          {
            "name": "Billing",
            "email": "billing@email.com"
          }
        ],
        "body": "",
        "payload": {
          "draftJs": {
            "blocks": [
              {
                "data": {},
                "entityRanges": [],
                "inlineStyleRanges": [],
                "depth": 0,
                "type": "unstyled",
                "text": "",
                "key": "dv926"
              }
            ],
            "entityMap": {}
          }
        },
        "status": "draft",
        "createdAt": "2016-11-07T23:21:16.945Z",
        "updatedAt": "2016-11-08T18:49:32.730Z",
        "modifiedAt": "2016-11-08T18:49:32.730Z"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "57f29863a1dbf61100e6aa92"
          },
          "links": {
            "self": "/v1/orgs/57f29863a1dbf61100e6aa92"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "58210c3db0f09110006b7953"
          },
          "links": {
            "self": "/v1/customers/58210c3db0f09110006b7953"
          }
        },
        "createdBy": {
          "data": {
            "type": "user",
            "id": "57fd2d309d0ef811009cfdd6"
          },
          "links": {
            "self": "/v1/users/57fd2d309d0ef811009cfdd6"
          }
        },
        "modifiedBy": {
          "data": {
            "type": "user",
            "id": "58190b991f2932100010d683"
          },
          "links": {
            "self": "/v1/users/58190b991f2932100010d683"
          }
        },
        "conversation": {
          "data": {
            "type": "conversation",
            "id": "58210c3d728107110018662f"
          },
          "links": {
            "self": "/v1/conversations/58210c3d728107110018662f"
          }
        }
      }
    },
    {
      "id": "58210cedbff98a10008531da",
      "type": "forward",
      "attributes": {
        "app": "gmail",
        "channel": "email",
        "body": "Hi John! ",
        "from": {
          "name": "Sales",
          "email": "sales@example.com"
        },
        "to": [
          {
            "name": "Billing",
            "email": "billing@email.com"
          }
        ],
        "payload": {
          "draftJs": {
            "blocks": [
              {
                "data": {},
                "entityRanges": [],
                "inlineStyleRanges": [],
                "depth": 0,
                "type": "unstyled",
                "text": "Hi John! ",
                "key": "a789"
              }
            ],
            "entityMap": {}
          }
        },
        "status": "draft",
        "createdAt": "2016-11-07T23:23:25.706Z",
        "updatedAt": "2016-11-09T16:13:12.665Z",
        "modifiedAt": "2016-11-09T16:13:12.665Z"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "57f29863a1dbf61100e6aa92"
          },
          "links": {
            "self": "/v1/orgs/57f29863a1dbf61100e6aa92"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "58210c3db0f09110006b7953"
          },
          "links": {
            "self": "/v1/customers/58210c3db0f09110006b7953"
          }
        },
        "createdBy": {
          "data": {
            "type": "user",
            "id": "57fd2d309d0ef811009cfdd6"
          },
          "links": {
            "self": "/v1/users/57fd2d309d0ef811009cfdd6"
          }
        },
        "modifiedBy": {
          "data": {
            "type": "user",
            "id": "5808d9c95cf6ce1100e1acda"
          },
          "links": {
            "self": "/v1/users/5808d9c95cf6ce1100e1acda"
          }
        },
        "conversation": {
          "data": {
            "type": "conversation",
            "id": "58210c99b0f09110006b7969"
          },
          "links": {
            "self": "/v1/conversations/58210c99b0f09110006b7969"
          }
        }
      }
    },
    {
      "id": "5823e4d3bff98a100085320e",
      "type": "forward",
      "attributes": {
        "app": "postmark",
        "channel": "email",
        "body": "A great response",
        "from": {
          "name": "Sales",
          "email": "sales@example.com"
        },
        "to": [
          {
            "name": "Billing",
            "email": "billing@email.com"
          }
        ],
        "status": "draft",
        "createdAt": "2016-11-10T03:09:07.575Z",
        "updatedAt": "2016-11-10T03:16:55.464Z",
        "modifiedAt": "2016-11-10T03:16:55.464Z"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "57f29863a1dbf61100e6aa92"
          },
          "links": {
            "self": "/v1/orgs/57f29863a1dbf61100e6aa92"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "58210c3db0f09110006b7953"
          },
          "links": {
            "self": "/v1/customers/58210c3db0f09110006b7953"
          }
        },
        "createdBy": {
          "data": {
            "type": "user",
            "id": "58190b991f2932100010d683"
          },
          "links": {
            "self": "/v1/users/58190b991f2932100010d683"
          }
        },
        "modifiedBy": {
          "data": {
            "type": "user",
            "id": "58190b991f2932100010d683"
          },
          "links": {
            "self": "/v1/users/58190b991f2932100010d683"
          }
        }
      }
    }
  ],
  "links": {
    "self": "/v1/conversations/58210c3db0f09110006b7953/forwards?page=1&pageSize=100",
    "first": "/v1/conversations/58210c3db0f09110006b7953/forwards?page=1&pageSize=100",
    "prev": null,
    "next": null
  }
}