Como funcionam as automações

Uma definition tem um trigger, o passo entry e uma lista de steps. Cada passo tem uma key única na automação: uma letra minúscula seguida de 2 a 23 letras minúsculas ou dígitos. Um passo indica o que se lhe segue em next, e um branch indica dois, yes e no. null termina esse caminho. Os passos formam uma árvore, por isso nenhum passo é alcançado a partir de dois sítios e nada volta atrás. Uma automação comporta até 50 passos, com ramificações de 5 níveis de profundidade no máximo.

• —audience_joined: um contacto é adicionado a audienceId. Os contactos adicionados por uma importação ficam de fora, a menos que includeImported seja true.
• —form_submitted: uma pessoa inscreve-se pelo formulário formId. Com dupla confirmação, entra quando confirma.
• —event: o seu código envia um evento chamado eventName. Até 5 filters sobre as propriedades restringem quem entra.
• —date: chega um dia para cada membro de audienceId. field é birthday ou joined, o aniversário do dia em que entrou nessa audiência. offsetDays desloca-o até um ano: negativo para dias antes, positivo para dias depois.
• —manual: ninguém entra sozinho. Adiciona as pessoas a partir da aplicação ou com o endpoint de inscrição.

Um valor em props ou em update_field vem de um de três sítios: { "source": "static", "value": "…" }, { "source": "contact", "field": "firstName" } para email, name, firstName, lastName ou attributes.<key>, e { "source": "event", "path": "orderId" } para uma propriedade do evento que iniciou o percurso.

Guardar altera a definition do rascunho. Nada é executado até POST /automations/{id}/publish fixar o rascunho como uma versão numerada, que published passa a mostrar. As pessoas que já estão dentro terminam na versão com que entraram, e as que entram depois recebem a nova. hasUnpublishedChanges diz que o rascunho avançou.

• —draft: nunca foi publicada. Ninguém entra.
• —live: publicada e em execução.
• —paused: ninguém entra e todos os que estão dentro ficam onde estão. pausedReason diz porquê: manual, ou um problema que o motor encontrou, como sender_refused ou template_unavailable.
• —archived: encerrada de vez. Todos os que estão dentro saem, e o histórico fica.

As settings são à parte e aplicam-se assim que são guardadas: o timezone, um sendWindow fora do qual os emails esperam, reentryDays até a mesma pessoa poder voltar a entrar (null significa uma só vez), exitOnLeave para retirar quem deixa a audiência do acionador, e listAudienceId, a audiência onde um cancelamento de subscrição é registado.

problems lista o que está errado no rascunho, cada item com um code, o path do campo, a stepKey e se é blocking. Um rascunho com um problema bloqueante não pode ser publicado.

Cada pessoa que entra recebe uma inscrição. Está active enquanto percorre os passos, completed quando chega ao fim de um caminho, e exited quando sai antes, com um exitReason: exit_step, unsubscribed, suppressed, left_audience, removed, archived ou failed.

• —Os passos são executados cerca de 15 segundos depois de chegar a sua hora. Uma pessoa nunca recebe dois emails de uma automação na mesma passagem.
• —Os emails de automação são correio de marketing, por isso todos levam uma ligação para cancelar a subscrição. Quem cancela a subscrição sai das automações que enviam para essa lista, e quem tem um endereço que devolveu correio ou apresentou queixa sai no passo seguinte.
• —Um email cujo endereço não pode receber correio é ignorado, e a pessoa segue para o passo seguinte.
• —Quando um envio é recusado para todos, como um remetente que perdeu o domínio ou um modelo que deixou de estar publicado, a automação entra em pausa e pausedReason diz porquê.

POST /events regista que um contacto fez algo: order.placed, trial.started, plan.upgraded. Um evento inicia todas as automações ativas cujo acionador o indica, faz avançar quem está à espera dele e responde à pergunta event de uma ramificação. Os eventos são guardados durante 90 dias.

• —Ler requer automations:read e alterar requer automations:write. Publicar, retomar e enviar um teste requerem também emails:send, porque fazem a automação enviar correio.
• —Enviar um evento requer contacts:write, e ler os eventos de um contacto requer contacts:read.
• —Uma chave de API e o proprietário veem todas as automações do espaço de trabalho. Uma aplicação que um membro ligou vê as que esse membro criou.
• —Eliminar uma automação pede um código de verificação a uma aplicação OAuth. Uma chave de API nunca precisa de um.
• —Um plano permite 1 automação ativa no Free, 10 no Starter, 50 no Business e qualquer número no Enterprise. Um espaço de trabalho comporta 100 automações por omissão.

Os webhooks automation.entered, automation.exited e automation.paused dizem aos seus sistemas quem entrou, quem saiu e quando uma automação parou. Arquivar uma automação termina o percurso de todos os que estão nela sem um evento automation.exited por pessoa.

Tudo o que aqui está existe também no SDK como openemail.automations e openemail.events, e na CLI como openemail automations e openemail events. O servidor MCP tem ferramentas de automações, por isso um agente pode construir uma, publicá-la e ver quem está dentro.