Referência da API

Use Agentic Inbox para conectar uma caixa de correio a um assistente, ou a API de gerenciamento para administrar os domínios, caixas de correio e apelidos da sua organização. Estes usam credenciais e permissões separadas. Escolha a integração que você precisa abaixo.

Agentic Inbox

Conecte-se através de OAuth com PKCE em https://franklymail.com/api/agent/mcp. A guia de ligação abrange ChatGPT e Claude. Iniciar sessão no Webmail. Cada subsídio OAuth está ligado a essa caixa de correio verificada. Utilização das subvenções mailbox.read, message.read, message.search e draft.write. Não há permissão automática de envio.

Os rascunhos devolvem um link de revisão. Somente uma sessão verificada para essa caixa de correio pode aprovar a versão atual exata. Uma sessão de conta do painel não pode consentir ou aprovar. Argumentos de ferramentas ou uma mensagem de chat não podem autorizar o envio.

Para pesquisas específicas de pastas, passe folder como inbox, sent, drafts, archive, trash ou junk (spam é um pseudônimo). Utilização list_folders e folderId para pastas personalizadas. Escolha um seletor; uma pasta em falta retorna um erro em vez de procurar por todo o e- mail. A omitir ambas as pastas.

prepare_forward exige mailboxId, messageId, requestKey e to; cc e introdutório text são opcionais. Exige ambos message.read e draft.write. Os cabeçalhos originais e o texto legível são incluídos automaticamente. Os anexos requerem o webmail, ou a escolha explícita do texto pelo usuário apenas usando omitAttachments: true. Os originais incompletos ou exagerados são rejeitados. Os esboços prévios utilizam o mesmo fluxo de revisão e homologação que as respostas.

A página de revisão humana suporta destinatários de edição, assunto e mensagem. Mailbox Boost também adiciona opcional Faixa aberta e Escrever com IA. A localização está desligada até ser seleccionada e salva. Uma mensagem partilhada enviada a vários destinatários não pode identificar qual o destinatário que a abriu. Proxies de privacidade podem afetar sinais abertos; atividade de visualização no webmail.

O escritor de IA requer o consentimento da caixa de correio e compartilha o subsídio de escrita do webmail. Ele usa o rascunho salvo, assunto, destinatários e instruções de escrita para preparar uma sugestão através de OpenAI. Aplicar uma sugestão é uma edição, seguida de salvar e uma nova aprovação humana. Nenhum dos recursos adiciona uma ferramenta MCP ou uma permissão de envio; os agentes não podem definir trackOpens ou ligue para o escritor do navegador.

OAuth utiliza código de autorização com S256 PKCE e resource=https://franklymail.com/api/agent/mcp. Descobrir a configuração em os metadados de recursos protegidos e metadados do servidor de autorização. O registro dinâmico do cliente é suportado. Os tokens de acesso duram uma hora; os tokens de atualização giram. A reutilização de um token de atualização revoga a conexão. Os subsídios duram até 90 dias.

MCP usa HTTP sem estado Streamable com respostas JSON. Chamada tools/list para esquemas. Chamadas bem- sucedidas incluem result.structuredContent; as falhas da ferramenta podem retornar HTTP 200 com result.isError=true e um bloco de texto JSON contendo error. Verifique a resposta HTTP e o resultado da ferramenta. Falhas de autenticação usam HTTP 401.

Rotas HTTP equivalentes: GET /api/v1/mailboxes/:id/messages, GET /api/v1/mailboxes/:id/messages/:messageId, POST /api/v1/drafts, GET /api/v1/drafts/:id e PUT /api/v1/drafts/:id. A pesquisa aceita folder ou folderId, text, from, subject, unread, limit (1 a 25) e position. O projecto de criação requer mailboxId, requestKey, to, subject, text; cc e replyToMessageId são opcionais. A revisão requer o atual version e os destinatários de substituição completos, assunto e texto.

A listagem de pastas e o encaminhamento usam as ferramentas MCP list_folders e prepare_forward; eles não têm rotas HTTP separadas. Os rascunhos suportam no máximo 10 destinatários To e Cc combinados, um assunto de 256 caracteres e uma mensagem de 20,000 caracteres, e expiram após 24 horas. Ficam em Agentic Inbox até serem aprovados; as mensagens enviadas aparecem no webmail.

Agentic Inbox permite 25 pedidos/dia e 5/minuto por caixa de correio; Boost eleva este para 2,500/dia e 60/minuto. As ligações à mesma caixa de correio partilham o seu subsídio. As alterações de senha revogam as sessões e conexões da caixa de correio. Os subsídios de caixa de entrada autorizados por conta existentes devem ser reconectados através do webmail. Subsídios diários repostos à meia-noite UTC. A revisão manual e a aprovação não utilizam este subsídio. Em um erro limite, respeito Retry-After e error.resetsAt; mostrar o link Boost fornecido na exaustão do plano padrão.

Para quem você pode criar caixas de correio

Uma conta é uma organização. Caixas de correio são para as pessoas na sua: pessoal, empreiteiros, seus próprios projetos, pseudônimos e endereços compartilhados. Eles são. não para clientes que você cobra ou serve. Revender FranklyMail caixas de correio, ou executar uma conta em nome de outra pessoa como um serviço que você é pago, é uma violação do termos. Veja a cláusula de revenda ali. Dirigir vários domínios que você possui é bom e sempre foi; uma holding com quinze marcas é uma organização. Uma agência com quinze clientes não é.

Não existe uma quota de caixa de correio para fazer cumprir essa distinção. Se uma conta cresce uma forma que lê como várias organizações, nós escrevemos e perguntamos. Nada é suspenso por causa de uma pergunta.

API de recursos legados: apenas metadados

Credenciais de recursos existentes mantêm suas permissões originais. Para habilitar o acesso ao conteúdo de e- mail, crie uma nova conexão usando o guia de conexão assistente. Chaves concedidas apenas domain.read e mailbox.read ler apenas metadados. Eles não podem ler mensagens, enviar e- mail ou alterar recursos. Caixas de correio e domínios recém-criados nunca ganham acesso automaticamente.

Enviar a chave como Authorization: Bearer fma_.... Os caminhos abaixo são relativos a https://franklymail.com/api.

Listas aceites limit de 1 a 100 (padrão 50) e um UUID cursor da resposta anterior. Eles voltam. { data: [...], nextCursor, requestId }; Retorno dos dados { data: {...}, requestId }. As contagens de bytes são cadeias decimais. DNS resultados são observações armazenadas.

O acesso restrito padrão permite 25 solicitações/dia e 5/minuto, compartilhados entre as chaves da conta. Mailbox Boost aumenta para 2.500/dia e 60/minutos por caixa de correio assinada. Dias reiniciados à meia-noite UTC. Limites-chave padrão para 60/minuto, ajustável de 1 a 600, com um teto de segurança de conta compartilhada separado de 600/minuto.

Cada caixa de correio Boost retornada usa um pedido de sua própria mesada. Qualquer recurso padrão na página compartilhar um pedido padrão. Todas as licenças necessárias devem estar disponíveis; uma página rejeitada não gasta nenhuma delas. Uma página vazia usa o subsídio padrão. Domínio e DNS leituras podem usar a franquia da primeira caixa de correio Boost por UUID nesse domínio, apenas quando a chave explicitamente concede mailbox.read para ele também. Isto não aumenta o acesso a outras caixas de correio.

Ligado 429, honra Retry-After e error.resetsAt. Usos diários de exaustão daily_quota_exceeded; utilização de limites mínimos rate_limited. Os limites do plano normal incluem: error.metadata.upgrade com a ligação Boost e subsídios mais elevados. Mostre esse link para a pessoa que gerencia a caixa de correio. Um agente não pode comprar uma atualização. Aumentar a exaustão e os limites de segurança chave / conta não têm oferta de atualização. X-Agent-Plan Identifica o acesso normalizado, potenciador ou misto; X-Agent-Daily-Limit, X-Agent-Daily-Remaining e X-Agent-Daily-Reset Descrever o subsídio diário exigido com os pedidos mais escassos. Os tectos-chave ainda contam negações autenticadas. Falta o escopo retorna 403; um recurso fora do subsídio retorna 404; uma chave expirada ou revogada retorna 401. Credenciais restritos funcionam em /api/v1 e /api/agent/mcp dentro dos seus âmbitos originais. Essas rotas não aceitam cookies de navegador nem chaves de gerenciamento.

Autenticação da API de gerenciamento

Escolha “Nova chave de gerenciamento” em Configurações → Chaves de API. É mostrado uma vez, na criação; armazenamos apenas um haxixe e não podemos mostrá-lo novamente. Envie-o como um símbolo portador em cada pedido:

curl -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     https://franklymail.com/api/mailboxes

Os pedidos são JSON e JSON fora. Um erro é { "error": { "code", "message", "field? } } com o estado HTTP correspondente: 401 para uma chave que esteja em falta, revogada ou desconhecida, 403 para uma rota que uma chave pode não alcançar, 422 para um campo mau.

curl -X POST https://franklymail.com/api/mailboxes \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domainId":"<uuid>","localPart":"sales"}'

O que uma chave de gestão pode chamar

Os caminhos são relativos a https://franklymail.com/api. Esta lista é exaustiva: uma rota que não está na lista responde 401 para uma chave, o que quer que ela faça para um navegador assinado.

Domínios

Caixas de correio

Outros nomes e encaminhamentos

Adicionando um domínio, passo a passo

POST /domains cria-o e devolve os registos para publicar. Nada mais tem de ser chamado para iniciar a verificação, uma vez que os controlos são executados no seu próprio horário.

curl -X POST https://franklymail.com/api/domains \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"example.com"}'

# {"id":"<uuid>","domain":"example.com","status":"pending",
#  "ownership":"unproven","sending":"pending","recheckIn":300,
#  "records":[{"key":"mx","type":"MX","host":"example.com","value":"…","status":"missing"},
#             {"key":"spf"…},{"key":"dkim"…},{"key":"dmarc"…}]}

Publicar cada records[] entrada em seu DNS provedor, em seguida, assistir GET /domains, a mesma carga útil para cada domínio, de modo que uma pesquisa cobre um lote inteiro. Três campos respondem a três perguntas diferentes, e conflitá-las é o erro habitual:

• records[].status: live uma vez DNS responde o que esperamos, missing Até lá.
• ownership: proven Uma vez que o recorde DKIM esteja pronto. Este é o que porta caixas de correio e importa, então o e-mail pode ser copiado muito antes do MX é trocado.
• status: todo o domínio, active quando tudo, incluindo MX é ao vivo e o correio vai realmente chegar.

recheckIn é segundos até a próxima verificação automática; dormir aproximadamente esse tempo entre as sondagens em vez de martelar. POST /domains/:id/recheck força um imediatamente e é taxa limitada por domínio, então use-o após a publicação de registros, não como um loop de votação. A rota é idempotent por conta e nome: re-posting um domínio que você já tem retorna o existente em vez de um duplicado ou um erro.

Movendo uma caixa de correio, passo a passo

Este é o fluxo que a maioria dos scripts são escritos para, e aquele com partes móveis vale a pena afirmar em vez de deixar para ser descoberto.

1. Liga-o. POST /mailboxes/:id/import com os detalhes de conexão do servidor antigo. A senha é criptografada antes de tocar uma coluna, nunca retornada por nenhuma rota, e limpa no momento em que o trabalho para.

curl -X POST https://franklymail.com/api/mailboxes/<mailboxId>/import \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"host":"imap.oldhost.com","port":993,"username":"you@old.com","password":"…"}'

# 202 {"importId":"<uuid>","status":"pending"}

Responde. 202, não 200: uma cópia leva minutos a horas, por isso o trabalho está em fila e a requisição retorna imediatamente. Uma importação de cada vez por caixa de correio. Iniciando um segundo enquanto um executa respostas 409 import_in_progress com o id do trabalho em execução, porque duas cópias simultâneas da mesma fonte duplicam cada mensagem e uma repetição não desfaz isso. Trinta caixas de correio podem importar de uma só vez; o limite é por caixa de correio, não por conta.

2. Siga-o. GET /mailboxes/:id/import retorna a última tarefa para essa caixa de correio, ou {"import": null} Se nunca houve um.

curl -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     https://franklymail.com/api/mailboxes/<mailboxId>/import

# {"import":{"id":"<uuid>","status":"running","folders_done":2,"folders_total":9,
#            "messages_done":1841,"messages_skipped":3,"current_folder":"INBOX",
#            "last_error":null,"started_at":"…","finished_at":null}}

status é um de pending, running, done, failed ou cancelled, e os três últimos são terminais. Poste-o na ordem de segundos, não milissegundos; as leituras não são limitadas, mas os contadores só se movem tão rápido quanto as respostas dos outros servidores. folders_done / folders_total é o valor do progresso honesto: messages_done não tem denominador até que uma pasta seja aberta, por isso uma percentagem construída dela irá saltar para trás. Em um fracasso, last_error carrega uma frase escrita para ser mostrada a uma pessoa.

3. Pára com isso, se quiseres.POST /mailboxes/:id/import/cancel acaba com o trabalho de corrida. Nada é mudado no antigo provedor por nada disso. Uma importação só lê a partir dela. As mensagens já copiadas permanecem, a menos que o pedido peça explicitamente o contrário.

Duas coisas que vale a pena saber antes de escreveres isto. Uma caixa de correio precisa do registro DKIM do seu domínio comprovado, não o cutover MX, então a cópia pode correr dias antes de você mudar o e-mail. E uma implantação nossa reinicia o painel: um trabalho que estava em execução pára e não retoma por si só, então um script que começa trinta importações deve verificar seu status depois, em vez de assumir o silêncio significa sucesso.

Apagar as coisas

Duas regras, e eles são os únicos lugares que esta API se recusa a fazer o que você pediu:

• Uma caixa de correio mantém o seu correio quando o apaga.DELETE /mailboxes/:id tira o endereço fora de serviço e deixa todas as mensagens onde está. Para destruir o e-mail também, a solicitação tem que dizer isso e confirmar a contagem exata de byte que o painel mostrou. Se a caixa de correio cresceu desde então, a destruição é recusada em vez de silenciosamente tomar o extra. Nada do que um agente faz por acidente pode destruir uma mensagem.
• Um domínio não pode ser excluído enquanto as caixas de correio estiverem nele. Tu tens... 409 domain_has_mailboxes listando os endereços e quais deles foram utilizados. Apagar cada caixa de correio em primeiro lugar: este é o passo em que a pergunta sobre o correio é feita, uma vez por caixa de correio, por quem tem o direito de respondê-lo.

Se for um agente: Não responda a nenhuma das perguntas em nome do ser humano. Excluir uma caixa de correio é reversível até que o correio seja destruído e nunca mais. Quando uma tarefa implica destruição, diga o que seria destruído e deixe a pessoa decidir.

A tirar o correio

Uma caixa de correio pode ser baixada como um zip de arquivos mbox, cada pasta, cada mensagem, mas não com uma chave API. GET /mailboxes/:id/export respostas 403 browser_only para uma chave, porque essa rota entrega o e-mail em si em vez da configuração ao seu redor, e uma chave vive exatamente nos lugares de onde os segredos vazam.

Para exportar: abra a caixa de correio no painel e use Download. Ele flui enquanto constrói, de modo que uma caixa de correio maior do que a memória ainda chega, e não há trabalho para esperar. Se você quiser isso de um terminal, entre no painel em um navegador e chame a mesma URL com essa sessão. A rota está inalterada, apenas as chaves são recusadas.

Faz isto. antes A apagar tudo o que quiseres. Uma exportação é a única cópia que sobrevive a uma destruição.

O que uma chave não pode fazer

Uma chave é examinada para uma conta e, dentro dela, para as três coisas acima. Ele não pode baixar uma caixa de correio, não pode alcançar faturamento, não pode registrar um domínio (que gasta dinheiro), não pode criar senhas de aplicativo, não pode alterar sua senha de conta ou 2FA, e não pode criar ou revogar outra chave de API, incluindo a própria. Todos eles precisam de um navegador assinado.

A razão é a forma da credencial em vez de desconfiar: uma chave vive em um .env arquivo, uma loja secreta de CI e o ambiente de um agente, e um segredo que vive em três lugares não deve ser capaz de ter uma conta sobre ou bloquear o seu proprietário. Se uma chave vazar, revogue-a em Configurações: o titular não pode fazer uma substituição primeiro.

O que essa fronteira não reivindica. Uma chave pode definir uma senha de caixa de correio, porque criar e distribuir caixas de correio é o trabalho para o qual ela existe, e qualquer um que possa definir uma senha de caixa de correio pode então entrar nessa caixa de correio mais de IMAP e lê-la. Fechando export Não muda isso, e fingir o contrário seria um tipo de segurança pior do que nenhum. O que isso muda é que o caminho não é mais silencioso: redefinir uma senha bloqueia o usuário real de sua própria caixa de correio, que é notado dentro de uma hora, enquanto um download não deixa nada para trás, mas uma linha de registro. Se esse comércio não é o que você quer para uma chave em particular, não crie a chave: chaves de gerenciamento não têm escopos por recurso. Use uma conexão Agentic Inbox OAuth para uma caixa de correio verificada através do webmail.

As chaves de gerenciamento não expiram. Dez chaves ao vivo por conta, que é um teto em vez de uma cota, então nomeá-las por script ou por máquina para revogar uma é uma decisão óbvia.

A alteração da senha da conta revoga todas as chaves, em uma rotação de rotina tanto quanto em uma recuperação. Ninguém pode distinguir esses dois no momento em que eles digitam uma nova senha, então a resposta segura não depende de saber qual era. Plano para ele: um script de longa duração deve falhar em voz alta em um 401 em vez de tentar novamente, e quem rodar a senha mete uma nova chave depois. Nós enviamos e-mail ao titular da conta sempre que uma chave é criada, e novamente quando uma mudança de senha os revoga, para que uma chave feita por outra pessoa não passe despercebida.

Limites de taxa de exportação e API de gerenciamento

Dois contadores, ambos por conta em vez de por chave, então girar uma chave não os redefiniu:

• 120 escreve a cada 5 minutos através de domínios, caixas de correio e nomes falsos. As leituras não são contadas, portanto, sondar um domínio até que ele verifique é gratuito. Mover dez domínios e trinta caixas de correio custa bem menos de uma centena escreve no total, de modo que o trabalho normal em massa não chega a isso.
• 30 caixas de correio exportam por hora. Uma exportação transmite todas as mensagens na caixa de correio, que é a coisa mais cara que esta API pode ser pedido para fazer.

Sobre qualquer um dos dois você tem 429 com { "error": { "code": "rate_limited" } } e a Retry-After cabeçalho em segundos. Espere esse tempo em vez de tentar novamente imediatamente: repetidamente bater no limite alonga a pausa. Se um trabalho legítimo precisa de mais espaço, escreva-nos em vez de trabalhar em torno dele; preferimos aumentar o número do que descobrir a partir de um projeto de lei.

Migrar vários domínios de uma vez

A ordem que funciona: POST /domains para cada nome, publicar os registros que retorna, pesquisa GET /domains até que cada um seja verificado, então POST /mailboxes por endereço. O correio pode ser copiado do antigo host antes do cutover MX, uma vez que um domínio só precisa de seu registro DKIM comprovado para POST /mailboxes/:id/import para correr, para que a migração e a transição não tenham de acontecer no mesmo dia.

MCP

Agentic Inbox fornece o ponto final MCP remoto em https://franklymail.com/api/agent/mcp Para leitura, pesquisa e preparação da caixa de correio. Conectar através de OAuth usando o guia de configuração. O provisionamento de domínio e a administração da caixa de correio usam a API HTTP de gerenciamento separada documentada acima.