Email Account

Email Account é um remetente SMTP que você registra em um Space. É um recurso que reúne e armazena em um só lugar o endereço do servidor pelo qual o e-mail será enviado, as credenciais de login e o endereço de remetente. Quando o statement EmailSend de um Script é executado, o e-mail real sai por meio deste Email Account. Por exemplo, em uma loja de roupas online, se você quiser enviar um e-mail de confirmação sempre que chega um pedido, primeiro registra o Email Account que será usado no envio e faz o Script referenciá-lo.

Email Account é um recurso sob o Space gerenciado pela CMA, e o caminho tem como base /spaces/{spaceId}/email-accounts. Não existe o conceito de publicação (publish). Sem valores de status nem etapas de publicação, assim que criado ele já pode ser usado no envio. Em contrapartida, a criação não é uma ação inofensiva de consulta, mas uma ação que realmente envia um e-mail para validar a configuração, e as informações de conexão (endpoint·username·password) não podem ser alteradas depois de criadas, o que é abordado a seguir.

Estrutura do recurso

A seguir está a resposta ao criar um Email Account. Em sys (propriedades do sistema) ficam o identificador e a versão, e no corpo ficam as configurações do remetente (name·endpoint·username·fromAddress·fromName). A senha (password) não aparece em lugar nenhum da resposta.

{
  "sys": {
    "id": "3trmXRMdKpLc7GfNbyVQeR2WsT9LnU",
    "type": "EmailAccount",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-08-04T05:12:44.108Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-08-04T05:12:44.108Z",
    "version": 1
  },
  "name": "Envio de notificações de pedidos",
  "endpoint": {
    "host": "smtp.gmail.com",
    "port": 587,
    "security": "StartTls"
  },
  "username": "orders@example-shop.com",
  "fromAddress": "orders@example-shop.com",
  "fromName": "Pedidos da loja de roupas"
}

Principais chaves:

• sys.id: o identificador único do Email Account. Entra em {emailAccountId} nos caminhos de consulta, edição e exclusão individuais.
• sys.version: a versão do recurso. Começa em 1 e aumenta a cada edição. Envie este valor na requisição de edição pelo cabeçalho X-Weegloo-Version (veja Status e restrições abaixo).
• name: o rótulo exibido no console (ex.: Envio de notificações de pedidos). Não é usado no envio e não é o nome exibido no From. É apenas um nome para distinguir vários remetentes.
• endpoint: o servidor SMTP ao qual se conectar. É composto por três valores: host·port·security.
• username: o nome de usuário de login SMTP. Varia conforme o provedor. Pode ser o próprio endereço de e-mail, uma string fixa definida pelo serviço de envio, ou um login por domínio.
• fromAddress: o endereço de remetente. É usado tanto como o remetente de retorno do envelope (MAIL FROM) quanto como o endereço From visível ao destinatário.
• fromName: o nome exibido no cabeçalho From (opcional). Se ausente, aparece apenas o endereço.

A senha (password) é um valor somente de escrita enviado apenas no corpo da requisição de criação, portanto não retorna nem na resposta acima nem em qualquer consulta ou listagem posterior. O username aparece na resposta de consulta exatamente como foi informado.

Propriedades do sistema (sys)

Todo Email Account carrega propriedades de sistema comuns no objeto sys. space, createdBy e updatedBy entram no formato Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Propriedades do corpo:

Entrada exclusiva do corpo da requisição de criação:

Informações do remetente e informações de conexão

Os valores de um Email Account dividem-se em dois tipos. Essa distinção determina o que pode ser editado.

• Informações de conexão — endpoint·username·password. Não podem ser alteradas depois da criação. Para trocar de servidor de envio ou rotacionar as credenciais de login, crie um novo Email Account e exclua o antigo. Como a senha, conforme explicado acima, não pode ser lida de novo, se você a perder, trate por recriação, não por redefinição.
• Informações do remetente — name·fromAddress·fromName. Podem ser alteradas mesmo após a criação, por edição (PUT). Use quando quiser organizar o rótulo ou trocar o endereço de remetente ou o nome exibido; nesse caso, as informações de conexão são mantidas como estão.

Na criação, um e-mail real é enviado

A criação de um Email Account não é uma ação que apenas salva a configuração. Antes de salvar, o servidor se conecta de fato com o endpoint·username·password informados e envia um e-mail de teste. O destino do envio é o fromAddress e, se o username for um endereço diferente, esse endereço também pode ser incluído.

• O recurso só é salvo se o envio for bem-sucedido.
• Se o servidor recusar em qualquer etapa (conexão, autenticação ou envio), a operação falha sem que nada seja criado, e a resposta traz junto o motivo da falha devolvido pelo servidor.

Portanto, tenha em mente que repetir a criação com valores incorretos dispara um envio real a cada tentativa.

Status e restrições

Restrições de valor a observar na criação e na edição.

Regras de comportamento e de permissão:

• As informações de conexão são imutáveis. O que pode ser alterado por Update (PUT) é apenas name·fromAddress·fromName. Para trocar endpoint·username·password, crie um novo e exclua o antigo.
• A edição exige a versão. Envie o valor atual de sys.version na requisição de Update pelo cabeçalho X-Weegloo-Version. Se o valor não estiver atualizado, a requisição é recusada por conflito de versão. Nesse caso, consulte o recurso de novo e tente novamente com o sys.version mais recente.
• A senha não pode ser lida de novo. Como não aparece em nenhuma consulta ou listagem, em caso de perda trate por recriação, não por redefinição.
• Os servidores SMTP disponíveis variam conforme o plano. Os hosts de provedores oferecidos como predefinição (Gmail·Naver·Resend·Brevo) podem ser registrados mesmo nos planos mais baixos. Um host arbitrário (auto-hospedado) que não esteja nas predefinições só pode ser usado se houver uma forma de pagamento registrada. Para a política por plano, consulte Planos.

API

A URL base de todos os endpoints abaixo é https://cma.weegloo.com/v1, e é necessário um token Bearer que autentique na CMA no cabeçalho Authorization. A edição (PUT) exige, adicionalmente, o cabeçalho X-Weegloo-Version.

Documentos relacionados

• Script: com o statement EmailSend, envia e-mail por meio deste Email Account.
• SpaceRole: o papel que define as permissões de acesso aos recursos deste Space.
• Planos: a política de uso dos hosts de provedores predefinidos e dos hosts SMTP arbitrários (auto-hospedados).