Legacy Mailbox API 1.0 is deprecated

Legacy Mailbox API 1.0 was deprecated on November 20, 2019. Please use Mailbox API 2.0 going forward. If you have any questions or need help with the new API, please reach out.

Create Conversation Thread

REST Method: POST
URL: https://api.helpscout.net/v1/conversations/{id}.json
Content-Type: application/json

Please note that threads cannot be added to conversations with 100 threads (or more), if attempted the API will respond with HTTP 412.

Response codes

Code	Description
200	when exists and it is not deleted, moved, merged, etc
301	The conversation exists under a different ID because it has either been moved or merged. The `location` header contains the location of the moved entity
404	when conversation does not exists or it is deleted

Request

Name	Type	Required	Default	Notes
thread	ConversationThread	Y		The body of the request (see example below).
imported	boolean	N	false	When the 'imported' request parameter is set to `true`, no outgoing emails or notifications will be generated.
reload	boolean	N	false	Set this request parameter to `true` to return the entire conversation in the response.

{
    "createdBy": {
        "id": 1234,
        "email": "customer@example.com",
        "type": "customer"
    },
    "type": "customer",
    "body": "I need your help with an issue I'm having.",
    "assignedTo": {
        "id": 2222
    },
    "status": "active",
    "createdAt": "2012-07-23T12:34:12Z",
    "cc": [
        "user1@example.com",
        "user2@example.com"
    ],
    "bcc": [
        "user3@example.com",
        "user4@example.com"
    ],
    "attachments": [
        {
            "hash": "7gjj3dg7fs3cvi956jjgfsw"
        },
        {
            "hash": "hfsf63fjgle8jglglksd285"
        }
    ]
}

Accepted Fields

Name	Type	Required	Default	Notes
createdBy	Person	Y		Set the 'type' property on the Person to specify 'user' or 'customer'. The 'type' property is required for this field. If the type of thread is 'message' or 'note' this must be a user. If the type of thread is 'customer' this must be a customer. If the type of thread is 'chat' or 'phone' this can be either 'user' or 'customer'. Depending on the type of Person, some fields are required: If the type is 'user', id is required. If the type is 'customer', id OR email is required. If an id is not specified, the customer will be looked up by email. If no customer exists with the email, it will be created (specifying first and last name is recommended).
type	string	Y		Options: note, message, customer, chat
body	string	Y
assignedTo	Person	N	anyone	The Help Scout user assigned to the conversation.
status	string	N	active	Options: active, pending, closed, spam
createdAt	datetime	N	now	Defaults to current UTC date/time
cc	Collection	N	empty	Collection of strings representing email addresses.
bcc	Collection	N	empty	Collection of strings representing email addresses.
attachments	Collection	N	empty	Collection of Attachment objects. An Attachment must be sent to the API prior to including it with a new conversation or thread. The Attachment 'hash' property is required. See the Create Attachment documentation for more information.

Response

Response	Name	Type	Notes
Header	Status	Integer	201

Status: 201 Created