Home Campaigns and proactive messages Open an email conversation via API

Open an email conversation via API

Last updated on Oct 02, 2026

When to use

  • Your system needs to start a support conversation by email, 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 regular conversation.
  • You need the same request to be safely repeatable, without creating two conversations or sending two emails.

To reach many people at once, use "Campanhas" (Campaigns). This API is for single sends: one contact per call.

Prerequisites

  • An email inbox already connected and working.
  • An access token for the Cloud Humans public API.
  • The inbox must not have the "Manter Conversa Ăšnica" (Keep Single Conversation) option turned on. With it enabled, the message would be appended to the old conversation and your subject would be ignored — that's why the API rejects the request with inbox_locked_to_single_conversation instead of doing something different from what you asked.

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": "Seu pedido foi enviado",
  "content": "Olá! Seu pedido saiu para entrega hoje.",
  "idempotency_key": "pedido-12345"
}

Identify the recipient by email or by contact_id — one of the two, never both together. With email, the contact is 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.

Repeat safely

Send your own idempotency_key, up to 128 characters. If the same key arrives 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.

CC and attachments

  • cc_emails and bcc_emails accept a list or comma-separated text, with a combined maximum of 25 addresses.
  • Use attachment_blob_ids for files already uploaded to the platform and attachment_urls for public links. There's a maximum of 10 attachments, up to 5 of them by URL.

When the API rejects the request

Code What happened
inbox_not_assigned The inbox doesn't exist or your access doesn't reach it
subject_required / content_required The subject or body is missing
invalid_email / invalid_recipient Malformed address
recipient_suppressed The address is undeliverable: it hard bounced, was marked as spam, or has already failed in this inbox
too_many_recipients / too_many_attachments The limits above were exceeded
email_claimed_by_another_contact The address already belongs to another contact in this inbox

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

Notes

  • The limit is 30 sends per minute per account.
  • The conversation is created marked as started by your team, which keeps response time metrics accurate.
  • The email is sent from the inbox itself, so the sender, signature and domain are the ones you have already configured.