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:code).
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||