Primeiros passos com Agent Accounts

O que é um Nylas Agent Account?

Seu agente de IA precisa enviar e receber e-mail. E-mail auto-hospedado significa 5 sistemas que você mantém sozinho: registros DNS MX (24-48 horas de propagação), um daemon SMTP como Postfix ou Exim (12 avisos de segurança desde 2020, segundo a lista oficial de anúncios), filtragem de spam via SpamAssassin, certificados TLS renovados trimestralmente e um parser MIME para o formato RFC 5322.

Um Nylas Agent Account substitui todos os 5 com um comando CLI. Você recebe uma identidade de e-mail totalmente gerenciada que envia e recebe sem credenciais OAuth, registros MX ou caixa de e-mail de terceiros. A API provisiona seu endereço em menos de 2 segundos e retorna um grant — o mesmo tipo de entidade usado para conexões Gmail, Outlook e IMAP — então todos os endpoints padrão de e-mail, calendário e contatos funcionam de forma idêntica. Seu endereço fica no domínio *.nylas.email, e a identidade se conecta à mesma superfície da API Nylas v3 que qualquer caixa de e-mail conectada via OAuth.

O que um Agent Account pode fazer?

Um Agent Account dá ao seu agente 3 capacidades em uma única identidade: e-mail, calendário e contatos. Um grant, uma chave de API, um workspace. Seu agente lê a caixa de entrada, consulta disponibilidade livre/ocupado e cria eventos de calendário — sem segundo serviço, sem integração separada. Concorrentes como Agentmail, Cloudflare Email Workers e Postmark oferecem contas de e-mail gerenciadas. Nenhum inclui endpoints de calendário ou contatos na mesma identidade.

Cada capacidade usa a mesma interface CLI e API que você já conhece das caixas de e-mail conectadas via OAuth. Se seu agente envia e-mail com nylas email send, ele também pode executar nylas calendar events list e nylas contacts list. Sem configuração extra. Sem credenciais adicionais. Para agentes de IA conectados via MCP, todas as 36 ferramentas estão disponíveis pela mesma conexão de servidor.

Como criar um agent account?

Criar um agent account leva um comando CLI e completa em menos de 2 segundos. O comando provisiona um grant com provider=nylas, cria automaticamente o connector gerenciado se ele não existir, e armazena o grant localmente para que comandos subsequentes o resolvam automaticamente. Sem handshake OAuth, sem propagação DNS, sem cliques no dashboard.

O comando nylas agent account create aceita o endereço de e-mail desejado como único argumento. O domínio é a zona *.nylas.email da sua aplicação. O endereço fica ativo e pronto para enviar em 2 segundos após o comando retornar:

nylas agent account create support@yourapp.nylas.email

✓ Agent account created successfully!

Email:      support@yourapp.nylas.email
Provider:   nylas
Status:     valid

Quando a conta existir, envie e-mail com o mesmo comando nylas email send usado para qualquer outro grant. O endereço do remetente é obtido automaticamente do grant ativo — sem necessidade do flag --from. A entrega completa em menos de 2 segundos com assinatura DKIM no domínio *.nylas.email:

nylas email send \
  --to customer@example.com \
  --subject "Your receipt" \
  --body "Order #4821 confirmed. Shipping Tuesday."

Para ler a caixa de entrada do agente, use nylas email list. Adicione --json para saída estruturada que loops de agentes e pipelines shell podem processar. A API Nylas v3 retorna até 200 mensagens por chamada:

nylas email list --limit 5 --json | jq '.[] | {from: .from[0].email, subject}'

Isso é uma identidade de agente funcional — criar, enviar, receber — em 3 comandos. Para o tutorial completo incluindo senhas de app para acesso IMAP/SMTP, verificações de status e limites de produção, veja Criar uma Identidade de E-mail para Agente IA.

Qual é a arquitetura do Agent Account?

O Agent Account é construído sobre uma cadeia de 5 entidades: Application, Connector, Grant, Workspace e Policy com Rules. A Application contém as chaves de API, o Connector define o tipo de provedor gerenciado, o Grant é a identidade de e-mail em si, o Workspace agrupa as associações de policy e rules, e Rules definem pares condição-ação que filtram e-mails de entrada e saída. Uma única application pode gerenciar centenas de agent accounts através dessa cadeia.

Cada entidade tem um papel específico:

• Application — seu contêiner de nível de projeto. Contém chaves de API, configurações de região (US ou EU) e todos os connectors. Criada uma vez no Nylas Dashboard.
• Connector — define o tipo de provedor. Para agent accounts, é o provedor gerenciado Nylas. A CLI o cria automaticamente na primeira chamada nylas agent account create — sem necessidade de configuração manual do connector.
• Grant (Agent Account) — a identidade de e-mail individual. Tem um endereço de e-mail, um campo de status e um workspace_id que o vincula à sua configuração. Funciona com todos os endpoints padrão de e-mail, calendário e contatos — o mesmo grant que lê a caixa de entrada também suporta nylas calendar events list e consultas de disponibilidade.
• Workspace — o ponto de conexão para configuração de policy e rules. Contém referências policy_id e rules_ids[]. Essa entidade é a camada arquitetural entre a identidade e suas restrições comportamentais.
• Policy — define restrições de saída para o workspace (limites de taxa, restrições de domínio).
• Rules — pares condição-ação. Cada regra faz matching nos campos do envelope como domínio do remetente ou destinatário, e dispara uma ação: block, archive, mark_as_read ou mark_as_starred.

O que é um workspace e por que ele existe?

Um workspace fica entre o grant do seu agent account e suas policies e rules. Em vez de armazenar policy_id diretamente nas configurações do grant, o workspace contém tanto policy_id quanto rules_ids[] como referências separadas. Por que isso importa? Você pode trocar policies sem tocar no grant, gerenciar rules independentemente das policies e compartilhar configurações entre contas.

Seu workspace fica em /v3/workspaces/{id} na API Nylas. Quando você cria um agent account, a API provisiona tanto o grant quanto o workspace em uma única chamada — menos de 2 segundos. Você nunca interage com o workspace diretamente. Quando executa nylas agent policy list, a CLI carrega seu grant padrão, busca o workspace, lê o policy_id do workspace e retorna a policy associada. A cadeia é invisível para você.

Três benefícios arquiteturais derivam dessa indireção:

1. Rotação de policy — troque policies atualizando o workspace, não o grant. A identidade permanece estável enquanto o comportamento muda. Zero downtime, menos de 200 ms por atualização.
2. Gerenciamento independente de rules — adicione ou remova rules no workspace sem tocar no objeto policy. O array rules_ids[] do workspace é a lista autoritativa de rules para aquela conta.
3. Multi-tenancy — contas diferentes podem apontar para o mesmo workspace quando compartilham restrições comportamentais, ou cada uma pode ter o seu próprio. Uma application com 50 agent accounts pode usar 3 workspaces: um para caixas de suporte, um para remetentes de notificação e um para automação de testes.

Benefício na prática: seu agente está enviando recibos de clientes através de uma policy que limita o volume de saída a 500/hora. Marketing quer aumentar o limite para uma campanha de lançamento. Sem workspaces, você alteraria as configurações do grant e arriscaria quebrar o agente durante o envio. Com workspaces, você troca a policy no workspace em uma única chamada PATCH. O grant não muda. O agente não reinicia. Menos de 200 ms, zero downtime.

Execute nylas agent account get para ver a vinculação do workspace em qualquer agent account. O campo Workspace ID conecta sua identidade à sua configuração:

nylas agent account get me@yourapp.nylas.email

Email:        me@yourapp.nylas.email
Provider:     nylas
Status:       valid
Workspace ID: ws_abc123

Como o e-mail de entrada chega a um agent account?

Alguém envia um e-mail para o endereço *.nylas.email do seu agente. A mensagem entra na infraestrutura de e-mail gerenciada da Nylas, resolve para o seu grant pelo endereço de e-mail, carrega o workspace e avalia rules em ordem de prioridade. Se nenhuma rule bloquear, a mensagem chega na caixa de entrada. O caminho completo do remetente externo até a mensagem entregue leva menos de 3 segundos para 95% das mensagens.

O caminho de entrada tem 4 estágios:

1. Resolução MX — A Nylas gerencia os registros MX de *.nylas.email. O servidor remetente se conecta à infraestrutura de e-mail da Nylas, não à sua. Nenhuma configuração DNS do seu lado.
2. Lookup do grant — o endereço do destinatário da mensagem é associado ao grant correspondente. Cada endereço de agente mapeia para exatamente um grant.
3. Avaliação de Policy / Rules — o workspace do grant é carregado, e a policy e cada rule em rules_ids[] são avaliados por prioridade. Rules fazem matching em campos do envelope: domínio do remetente, endereço do remetente, linha de assunto.
4. Entrega ou bloqueio — se uma rule dispara block, a mensagem é rejeitada. Caso contrário, chega na caixa de entrada e aciona qualquer webhook message.created registrado.

Como o e-mail de saída deixa um agent account?

Seu agente chama nylas email send ou faz uma requisição para a API Messages v3. A requisição resolve seu grant ativo, carrega o workspace, avalia sua policy de saída e roteia a mensagem pelo pipeline de envio transacional da Nylas. Dois segundos da resolução do grant até o servidor de e-mail do destinatário.

O caminho de saída tem 4 estágios:

1. Resolução do grant — a CLI resolve o grant ativo do agent account. O endereço do remetente é obtido automaticamente do grant — sem necessidade do flag --from.
2. Lookup do workspace — o workspace_id do grant é buscado. O workspace contém a policy e as rules que governam o comportamento de saída.
3. Avaliação de Policy / Rules — restrições de saída e rules são verificadas. Se a policy restringe o domínio do destinatário, uma rule bloqueia o envio, ou a taxa de envio excede os limites, a requisição é rejeitada antes de chegar ao SMTP.
4. Envio transacional — a Nylas assina a mensagem com DKIM para o domínio *.nylas.email e entrega ao servidor de e-mail do destinatário. Um webhook message.send_success é disparado na entrega.

Por que o Agent Account substitui e-mail auto-hospedado?

E-mail auto-hospedado exige 5 sistemas separados, cada um com sobrecarga de manutenção e segurança. De acordo com a lista oficial de anúncios do Postfix, o MTA open-source mais popular publicou 12 avisos de segurança desde 2020. Cada aviso significa um patch, um restart e um teste de verificação. O Agent Account substitui todos os 5 sistemas com uma chamada de API que provisiona uma caixa funcional em menos de 2 segundos.

A diferença arquitetural é que o Agent Account coloca a infraestrutura de e-mail por trás de uma fronteira de API. Você não gerencia daemons, certificados ou registros DNS — você chama um endpoint. A aplicação de policies e rules acontece na camada do workspace antes das mensagens tocarem o SMTP, então uma injeção de prompt direcionada a um agente de IA não consegue burlar as restrições. Para o padrão completo de contenção, veja Evite que seu Agente de IA Perca o Controle.

Agent accounts também suportam domínios personalizados — você pode enviar e receber do seu próprio domínio em vez de *.nylas.email. Para prototipagem rápida e automação de testes, o domínio gerenciado funciona sem configuração adicional. Quando estiver pronto para branding de produção, configure seu domínio personalizado pelo Nylas Dashboard.

Próximos passos

• Criar uma Identidade de E-mail para Agente IA — tutorial prático: criar conta, adicionar senha de app, enviar e receber em 2 minutos
• Guia Completo de Rules e Policies para Agentes — todos os triggers, condições, operadores, ações e configurações de policy com exemplos reais
• Evite que seu Agente de IA Perca o Controle — anexe uma policy e rules de contenção ao workspace antes de deixar o agente enviar
• Dê ao seu Agente de Código IA um Endereço de E-mail — conecte Claude Code, Cursor ou Codex a uma identidade de agente via MCP
• Receber E-mail sem Servidor SMTP — webhooks, processamento em tempo real e caixas de entrada isoladas por teste
• Comunicação de E-mail entre Agentes — crie dois agent accounts e troque JSON estruturado entre eles
• Melhor Infraestrutura de E-mail para Agentes IA — compare Agent Accounts, APIs de provedores, IMAP, SMTP, MCP e ferramentas CLI
• Referência completa de comandos — cada flag e subcomando nylas agent
• Documentação da API Nylas v3 — a superfície de API à qual os grants do Agent Account se conectam