Open Email Conversation via API

When to Use

Your system needs to initiate an email support session without waiting for the customer to write first.
You want to send a transactional email (confirmation, billing, delivery notice) and have the customer's reply land in your Cloud Chat inbox as a normal conversation.
You need the same request to be safely repeatable without creating duplicate conversations or emails.

To contact many people at once, use Campaigns. This API is for single dispatch: one contact per call.

Prerequisites

An email inbox already connected and operational.
An API access token for Cloud Humans.
The inbox must not have the Maintain Single Conversation option enabled. If it is active, messages will be appended to the old conversation and your subject will be ignored — hence the API will reject with inbox_locked_to_single_conversation, instead of doing something different from what you requested.

How It Works

Call

POST /cloudchat/v1/accounts/{account_id}/conversations

Headers: Authorization: Bearer <token> and cloudchat-instance.

{
  "inbox_id": 12,
  "email": "[email protected]",
  "name": "Maria Silva",
  "subject": "Your order has been shipped",
  "content": "Hello! Your order is out for delivery today.",
  "idempotency_key": "order-12345"
}

Identify the recipient by email or by contact_id — only one, never both. With email, the contact will be created if it doesn't exist yet.

The response includes id (conversation number), message_id, and dispatch_status, which is created for a new send and duplicate for a repeat.

Safe Repeat

Send your own idempotency_key, up to 128 characters. If the same key is received again, the API does not create another conversation or send another email: it returns the original conversation with dispatch_status: duplicate. The key is valid for 24 hours.

The key is per inbox: the same key in another inbox is a new send, not a repeat.

Reusing a key with different content is rejected with idempotency_key_payload_mismatch, instead of silently discarding the new message.

Copies and Attachments

cc_emails and bcc_emails accept a list or comma-separated text, up to 25 addresses.
Use attachment_blob_ids for files already uploaded to the platform and attachment_urls for public links. Up to 10 attachments, with a maximum of 5 per URL.

When the API Rejects

Code	What happened
`inbox_not_assigned`	The inbox does not exist or is not accessible
`subject_required` / `content_required`	Subject or body missing
`invalid_email` / `invalid_recipient`	Malformed address
`recipient_suppressed`	Undeliverable address: hard bounce, marked as spam, or already failed in this inbox
`too_many_recipients` / `too_many_attachments`	Limits exceeded
`email_claimed_by_another_contact`	Address already belongs to another contact in this inbox

Each code is stable: handle it in your system instead of reading the message text.

Notes

Limit of 30 sends per minute per account.
The conversation is marked as initiated by you, maintaining correct response time metrics.
The email is sent from your configured inbox, so sender, signature, and domain are as you set up.