Iniciar conversa por e-mail

Envia um e-mail individual a um lead (leadId) ou a um endereço (address, o lead é encontrado pelo e-mail ou um contato de e-mail é criado) e abre ou reaproveita a conversa de e-mail desse contato no inbox, com o e-mail registrado nela pelo operador e a conversa atribuída a ele: o agente ou fluxo da caixa não responde ao contato enquanto ele for o responsável (uma conversa de um colega continua com o colega, e uma delegação feita por uma pessoa continua valendo). O corpo é text (texto simples com {{first_name}}, {{name}}, {{email}}, {{company}} e {{field.chave}}) ou designId (um modelo salvo), nunca os dois; senderId vazio usa o remetente padrão. Cada envio é cobrado da carteira pelo preço de GET /v1/email/outreach/quote e devolvido se o provedor recusar. O cabeçalho Idempotency-Key é obrigatório e deve ser gerado uma vez por composição: repetir a mesma chave devolve a mesma conversa e a mesma mensagem (200) sem cobrar nem enviar de novo. Recusas antes de qualquer cobrança: 400 email_idempotency_key_required, email_recipient_missing, email_address_invalid; 403 email_lead_blocked, email_outreach_forbidden (remetente de um departamento fora do seu acesso); 404 email_lead_not_found, email_design_not_found; 409 email_lead_opted_out, email_sender_missing, email_send_in_progress; 422 email_lead_no_email, email_message_invalid, email_subject_invalid; 402 email_balance_insufficient (details.missingMicros). Depois da cobrança, com reembolso: 409 email_recipient_suppressed, email_sender_not_verified, email_account_paused; 429 email_daily_cap_reached; 429 email_send_throttled quando o provedor está no limite de envio agora (cabeçalho Retry-After e details.retryAfterSeconds em segundos inteiros; repita com a mesma chave depois desse tempo, o envio sai uma vez e é cobrado uma vez); 503 email_account_reactivation_failed; 502 email_send_failed. Depois do envio: 503 email_starter_not_assigned quando o e-mail saiu mas a conversa não pôde ser atribuída a quem a iniciou; repita com a mesma chave, que não envia nem cobra de novo e tenta atribuir outra vez. recorded falso quer dizer que o e-mail saiu mas não pôde ser registrado no inbox; repetir a mesma chave tenta registrar de novo sem reenviar. Envie handOff ({kind: agent ou workflow, id, values}) para que a conversa já comece com um agente de IA ou um fluxo: exige a permissão conversations:delegate, o agente precisa estar ativo e o fluxo publicado e ativo, e values traz as variáveis que a automação exige (veja GET /automation-needs). A passagem é conferida antes de qualquer envio ou cobrança: 403 hand_off_forbidden, 400 automation_invalid, 422 automation_unusable, 409 automation_variables_missing (details.variables com as que faltam), 422 conversation_variable_type_invalid e 400 conversation_variable_not_needed. A conversa começa com quem a iniciou e passa ao escolhido logo depois; handOff na resposta diz se passou (delegated, owner ai: ou workflow:) ou, se algo mudou nesse meio tempo, por que ficou com quem iniciou (code).

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Destinatário, remetente e conteúdo

string
string
handOff
object
string
string
string
string
Headers
string
required

Chave gerada uma vez por composição

string

Departamento que limita os dados. Quem não participa do departamento recebe 403; donos e administradores escolhem qualquer um.

Responses

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json