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

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

Please note that conversation cannot be created with more than 100 threads, if attempted the API will respond with HTTP 412.

Request

Name	Type	Required	Default	Notes
conversation	Conversation	Y		The body of the request (see example below).
imported	boolean	N	false	The 'imported' request parameter enables conversations to be created for historical purposes (i.e. if moving from a different platform, you can import your history). When 'imported' is set to `true`, no outgoing emails or notifications will be generated.
autoReply	boolean	N	false	The 'autoReply' request parameter enables auto replies to be sent when a conversation is created via the API. When 'autoReply' is set to `true`, an auto reply will be sent as long as there is at least one 'customer' thread in the conversation.
reload	boolean	N	false	Set this request parameter to `true` to return the created conversation in the response.

{
    "type": "email",
    "customer": {
        "id": 1234,
        "email": "customer@example.com"
    },
    "subject": "I need help",
    "mailbox": {
        "id": 4321
    },
    "tags": [
        "tag1",
        "tag2"
    ],
    "status": "active",
    "createdAt": "2012-07-23T12:34:12Z",
    "threads": [
        {
            "type": "customer",
            "createdBy": {
                "id": 1234,
                "email": "customer@example.com",
                "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"
                }
            ]
        }
    ],
    "customFields" : [
        {
            "fieldId": 10,
            "value": "Custom Support"
        },
        {
            "fieldId": 11,
            "value" : "10.5"
        },
        {
            "fieldId": 12,
            "value" : "2015-12-01 12:20:20"
        }
    ]
}

Accepted Conversation Fields

Name	Type	Required	Default	Notes
type	string	N	email	Options are 'email', 'chat' or 'phone'
customer	Person	Y		Must contain a valid customer id OR an email address. If an id is specified, email is not required, but recommended. 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). Phone is recommended if the type of Conversation is 'phone'.
subject	string	Y
mailbox	MailboxRef	Y
tags	Collection	N		Collection of strings representing tags.
createdAt	datetime	N	Current UTC date/time
threads	Collection	Y		One or more Threads - maximum of 100 threads allowed. Application will return HTTP 412 when the payload contains more than 100 threads. See the next section for accepted thread fields.
customFields	Collection	N		One or more Custom Field responses

Accepted Thread Fields

Name	Type	Required	Default	Notes
type	string	Y		Options: note, message, customer, chat, phone.
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).
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	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.
state	String	N	published	Set to `draft` to create a draft. Thread state: draft published

Response

Response	Name	Type	Notes
Header	Status	Integer	201
Header	Location	String	https://api.helpscout.net/v1/conversations/{id}.json

Status: 201 Created
Location: https://api.helpscout.net/v1/conversations/{id}.json