Referencia de API

Utilice Agentic Inbox para conectar un buzón a un asistente, o la API de gestión para administrar los dominios de su organización, buzones y alias. Estos utilizan credenciales y permisos separados. Elija la integración que necesita a continuación.

Agentic Inbox

Conectar a través de OAuth con PKCE https://franklymail.com/api/agent/mcp. El guía de conexión cubre ChatGPT y Claude de configuración. Inicie sesión en el correo electrónico. Cada subvención de OAuth está vinculada a ese buzón de correo verificado. Uso de subvenciones mailbox.read, message.read, message.search y draft.write. No hay permiso de envío automático.

Los proyectos devuelven un enlace de revisión. Sólo una sesión verificada para ese buzón de correo puede aprobar la versión actual exacta. Una sesión de la cuenta del panel no puede consentir o aprobar. Los argumentos de la herramienta o un mensaje de chat no pueden autorizar el envío.

Para búsquedas específicas de carpetas, pase folder como tal inbox, sent, drafts, archive, trash o junk (spam es un alias). Uso list_folders y folderId para carpetas personalizadas. Elija un selector; una carpeta que falta devuelve un error en lugar de buscar todo el correo. Omitir ambas búsquedas en cada carpeta.

prepare_forward Requisitos mailboxId, messageId, requestKey y to; cc y introductoria text son opcionales. Requiere ambos message.read y draft.write. Los encabezados originales y el texto legible se incluyen automáticamente. Los adjuntos requieren correo web, o la elección explícita del usuario del texto solamente utilizando omitAttachments: true. Los originales incompletos o sobredimensionados son rechazados. Los proyectos anteriores utilizan la misma corriente de revisión y aprobación que las respuestas.

La página de revisión humana es compatible con los destinatarios de edición, sujeto y mensaje. Mailbox Boost también añade opcional Se abre la pista y Escribe con AI. El seguimiento está apagado hasta que se selecciona y se guarda. Un mensaje compartido enviado a varios destinatarios no puede identificar qué destinatario lo abrió. Los proxies de privacidad pueden afectar las señales abiertas; ver actividad en el correo web.

El escritor de AI requiere el consentimiento de buzón y comparte el subsidio de escritura de correo electrónico. Utiliza el borrador, el tema, los destinatarios y las instrucciones de escritura guardadas para preparar una sugerencia a través de OpenAI. Aplicar una sugerencia es una edición, seguida de salvar y una nueva aprobación humana. Ninguna característica añade una herramienta MCP o un permiso de envío; los agentes no pueden establecer trackOpens o llame al escritor del navegador.

OAuth utiliza el código de autorización con S256 PKCE y resource=https://franklymail.com/api/agent/mcp. Descubra la configuración los metadatos de recursos protegidos y metadatos del servidor de autorización. Se admite el registro dinámico del cliente. Las fichas de acceso duran una hora; las fichas de actualización giran. Reutilizar un token refresca la conexión. Las subvenciones duran hasta 90 días.

MCP utiliza HTTP apátridas Streamable con respuestas JSON. Call tools/list para los esquemas. Las llamadas exitosas incluyen result.structuredContent; las fallas de la herramienta pueden devolver HTTP 200 con result.isError=true y un bloque de texto JSON que contiene error. Compruebe tanto la respuesta HTTP como el resultado de la herramienta. Las fallas de autenticación usan HTTP 401.

Rutas de HTTP equitativas: GET /api/v1/mailboxes/:id/messages, GET /api/v1/mailboxes/:id/messages/:messageId, POST /api/v1/drafts, GET /api/v1/drafts/:id y PUT /api/v1/drafts/:id. La búsqueda acepta folder o folderId, text, from, subject, unread, limit (1 a 25) y position. El proyecto de creación requiere mailboxId, requestKey, to, subject, text; cc y replyToMessageId son opcionales. La revisión requiere la corriente actual version y los receptores de reemplazo completos, sujeto y texto.

La lista de carpetas y el reenvío utilizan las herramientas MCP list_folders y prepare_forward; no tienen rutas HTTP separadas. Los proyectos de apoyo a la mayoría de los receptores 10 To y Cc combinados, un sujeto de 256 caracteres y un mensaje de 20,000 caracteres, y expiran después de 24 horas. Se quedan en Agentic Inbox hasta que se apruebe; los mensajes enviados aparecen en el correo electrónico.

Agentic Inbox permite 25 solicitudes/día y 5/minuto por buzón de correo; Boost eleva esto a 2,500/día y 60/minuto. Las conexiones al mismo buzón comparten su asignación. Cambios de contraseña revocan las sesiones y conexiones del buzón de correo. Las subvenciones de la caja de entrada autorizadas por cuenta existente deben volver a conectarse a través del correo electrónico. Los subsidios diarios se reinician a medianoche UTC. El examen y la aprobación manuales no utilizan esta prestación. Sobre un error límite, respeto Retry-After y error.resetsAt; mostrar el enlace Boost suministrado en el agotamiento del plan estándar.

¿Quién puede crear buzones de correo para

Una cuenta es una organización. Los buzones de correo son para la gente en el suyo: personal, contratistas, sus propios proyectos, alias y direcciones compartidas. Ellos son no para los clientes que cobran o sirven. Reventar FranklyMail buzones de correo, o ejecutar una cuenta en nombre de otra persona como un servicio que se paga, es una violación de la términos. Vea la cláusula de reventa allí. Ejecutar varios dominios que posees está bien y siempre ha sido; una empresa de tenencia con quince marcas es una organización. Una agencia con quince clientes no lo es.

No hay cuota de cuenta de correo para hacer cumplir esa distinción. Si una cuenta crece una forma que se lee como varias organizaciones, escribimos y preguntamos. Nada se suspende sobre una pregunta.

API de recursos de Legacy: metadatos solamente

Las credenciales de recursos existentes mantienen sus permisos originales. Para permitir el acceso al contenido de correo, cree una nueva conexión usando el Asistente de guía de conexión. Claves concedidas solamente domain.read y mailbox.read leer metadatos solamente. No pueden leer mensajes, enviar correos o cambiar recursos. Nuevos buzones y dominios creados nunca obtienen acceso automáticamente.

Enviar la llave como Authorization: Bearer fma_.... Los caminos a continuación son relativos a https://franklymail.com/api.

Listas aceptan limit de 1 a 100 (por defecto 50) y un UUID cursor de la respuesta anterior. Ellos regresan. { data: [...], nextCursor, requestId }; retorno de los detalles { data: {...}, requestId }. Los números de byte son cadenas decimales. DNS resultados se almacenan observaciones.

El acceso restringido estándar permite 25 solicitudes/día y 5/minuto, compartido a través de las claves de la cuenta. Mailbox Boost eleva esto a 2500/día y 60/minuto por buzón suscrito. Días de reajuste a medianoche UTC. Techos clave por defecto a 60/minuto, ajustables de 1 a 600, con un techo separado de seguridad de cuenta compartida de 600/minuto.

Cada buzón Boost devuelto utiliza una solicitud de su propio subsidio. Los recursos estándar en la página comparten una solicitud estándar. Todos los subsidios requeridos deben estar disponibles; una página rechazada no gasta ninguno de ellos. Una página vacía utiliza la asignación estándar. Dominio y DNS lecturas pueden utilizar la asignación del primer buzón Boost por UUID en ese dominio, sólo cuando la clave otorga explícitamente mailbox.read Para eso también. Esto no aumenta el acceso a otros buzones de correo.

On 429, honor Retry-After y error.resetsAt. Usos diarios de agotamiento daily_quota_exceeded; uso de límites mínimos rate_limited. Los límites de los planes estándar incluyen error.metadata.upgrade con el enlace Boost y mayores subsidios. Mostrar ese enlace a la persona que administra el buzón de correo. Un agente no puede comprar una actualización. Los techos de cansancio y seguridad clave/cuenta no tienen oferta de actualización. X-Agent-Plan Identifica el acceso estándar, el impulso o mixto; X-Agent-Daily-Limit, X-Agent-Daily-Remaining y X-Agent-Daily-Reset describir el subsidio diario requerido con las más pocas solicitudes que quedan. Los techos clave todavía cuentan las negaciones autenticadas. Desaparecimiento del alcance 403; un recurso fuera del retorno de la subvención 404; una llave caducada o revocada devuelve 401. Funcionamiento de las credenciales restringidas /api/v1 y /api/agent/mcp dentro de sus alcances originales. Esas rutas no aceptan cookies del navegador ni claves de gestión.

Manejo de autenticación API

Elija “Nueva clave de gestión” bajo Ajustes → Claves de API. Se muestra una vez, en la creación; almacenamos sólo un hash y no podemos mostrarlo de nuevo. Envíelo como una señal de portadora en cada solicitud:

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

Las solicitudes son JSON y JSON afuera. Un error es { "error": { "code", "message", "field? } } con el estado de HTTP coincidente: 401 para una llave que falta, revocada o desconocida, 403 para una ruta que una llave no puede llegar, 422 para un mal campo.

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

Qué clave de gestión puede llamar

Los caminos son relativos a https://franklymail.com/api. Esta lista es exhaustiva: una ruta que no responde 401 a una llave, lo que sea que haga para un navegador firmado.

Dominios

Mailboxes

Aliases y reenvío

Agregar un dominio, paso a paso

POST /domains lo crea y devuelve los registros para publicar. No hay nada más que llamar para iniciar la verificación, ya que los cheques se ejecutan en su propio horario.

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"…}]}

Publish each records[] entrada en su proveedor DNS y luego ver GET /domains, la misma carga de pago por cada dominio, por lo que una encuesta cubre un lote entero. Tres campos responden a tres preguntas diferentes, y conflarlas es el error habitual:

• records[].status: live una vez DNS responde lo que esperamos, missing hasta entonces.
• ownership: proven una vez que el récord de DKIM haya terminado. Este es el que porta buzones e importaciones, por lo que el correo puede ser copiado en mucho antes de que se cambie el MX.
• status: todo el dominio, active cuando todo lo que incluye MX es en vivo y el correo realmente llegará.

recheckIn es segundos hasta el siguiente cheque automático; dormir aproximadamente ese largo entre las encuestas en lugar de martillar. POST /domains/:id/recheck fuerza uno inmediatamente y es tarifa limitada por dominio, por lo que utilizarlo después de publicar registros, no como un bucle de votación. La ruta es idempotente por cuenta y nombre: re-postando un dominio que ya tiene devuelve el existente en lugar de un duplicado o un error.

Moviendo un buzón, paso a paso

Este es el flujo que la mayoría de los scripts están escritos para, y el que con partes móviles vale la pena decir en lugar de dejar para ser descubierto.

1. Comienza. POST /mailboxes/:id/import con los detalles de conexión del antiguo servidor. La contraseña está encriptada antes de que toque una columna, nunca devuelta por ninguna ruta, y despeja el momento en que el trabajo se detiene.

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, no 200: una copia toma minutos a horas, por lo que el trabajo es apagado y la solicitud regresa inmediatamente. Una importación a la vez por correo. Comenzando un segundo mientras uno corre respuestas 409 import_in_progress con la id del trabajo de ejecución, porque dos copias concurrentes de la misma fuente duplican cada mensaje y una retry no deshacer eso. Treinta buzones pueden importar a la vez; el límite es por buzón de correo, no por cuenta.

2. Síguelo. GET /mailboxes/:id/import devuelve el último trabajo para ese buzón de correo, o {"import": null} si nunca ha habido uno.

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 es uno de los pending, running, done, failed o cancelledY los últimos tres son terminales. Contadlo en el orden de segundos, no milisegundos; las lecturas no son limitadas pero los contadores sólo se mueven tan rápido como el otro servidor responde. folders_done / folders_total es la figura de progreso honesta: messages_done no tiene denominador hasta que se abra una carpeta, por lo que un porcentaje construido a partir de ella saltará hacia atrás. En un fracaso, last_error lleva una frase escrita para ser mostrada a una persona.

3. Basta, si es necesario.POST /mailboxes/:id/import/cancel termina con el trabajo de correr. Nada se cambia en el viejo proveedor por cualquiera de esto. Una importación sólo lee de ella. Los mensajes ya copiados permanecen a menos que la solicitud pida explícitamente otra cosa.

Dos cosas vale la pena saber antes de escribir esto. Un buzón de correo necesita el registro DKIM de su dominio probado, no el recortado completo MX, por lo que la copia puede ejecutar días antes de cambiar el correo. Y un despliegue de los nuestros reinicia el panel: un trabajo que estaba ejecutando paradas y no se reanuda por sí mismo, por lo que un script que comienza treinta importaciones debe comprobar su estado después en lugar de asumir silencio significa éxito.

Eliminar las cosas

Dos reglas, y son los únicos lugares que esta API se niega a hacer lo que pidió:

• Un buzón guarda su correo cuando lo elimina.DELETE /mailboxes/:id saca la dirección del servicio y deja cada mensaje donde está. Para destruir el correo también, la solicitud tiene que decirlo y confirmar el número exacto de byte que el panel le mostró. Si el buzón ha crecido desde entonces, la destrucción se niega en lugar de tomar silenciosamente el extra. Nada que un agente haga por accidente puede destruir un mensaje.
• Un dominio no se puede eliminar mientras que los buzones de correo están en él. Te pillo. 409 domain_has_mailboxes enumerar las direcciones y cuáles de ellas se han utilizado. Eliminar cada buzón primero: ese es el paso donde se hace la pregunta sobre el correo, una vez por correo, por quien tiene derecho a contestarlo.

Si usted es un agente: no responda a ninguna pregunta en nombre del humano. Eliminar un buzón es reversible hasta que el correo sea destruido y nunca después. Cuando una tarea implica la destrucción, diga lo que sería destruido y deje que la persona decida.

Sacar el correo

Un buzón se puede descargar como una cremallera de archivos mbox, cada carpeta, cada mensaje, pero no con una clave de API. GET /mailboxes/:id/export respuestas 403 browser_only a una clave, porque una ruta entrega el correo en sí mismo en lugar de la configuración alrededor de ella, y una clave vive en exactamente los lugares secretos de fuga.

Para exportar: abra el buzón en el panel y utilice Download. Fluye a medida que se construye, por lo que un buzón de correo más grande que la memoria todavía llega, y no hay trabajo que esperar. Si lo desea desde un terminal, ingrese al panel en un navegador y llame a la misma URL con esa sesión. La ruta no cambia, sólo se rechazan las llaves.

Haz esto. antes Eliminar todo lo que quieras de vuelta. Una exportación es la única copia que sobrevive a una destrucción.

Lo que una llave no puede hacer

Una clave se engloba a una cuenta y, dentro de ella, a las tres cosas anteriores. No puede descargar un buzón de correo, no puede llegar a facturación, no puede registrar un dominio (que gasta dinero), no puede crear contraseñas de aplicaciones, no puede cambiar su contraseña de cuenta o 2FA, y no puede crear o revocar otra clave de API, incluso ella misma. Todos necesitan un navegador firmado.

La razón es la forma de la credencial en lugar de desconfianza: una clave vive en una .env archivo, una tienda secreta de CI y un ambiente de agente, y un secreto que vive en tres lugares no debe ser capaz de tener una cuenta o bloquear a su dueño. Si se filtra una clave, revoquela en Ajustes: el titular no puede acuñar primero un reemplazo.

Lo que ese límite no reclama. Una clave puede establecer una contraseña de buzón, porque crear y entregar buzones de correo es el trabajo que existe para, y cualquiera que pueda establecer una contraseña de buzón puede firmar en ese buzón de correo más de IMAP y leerla. Cierre export no cambia eso, y pretender que otra cosa sería una clase peor de seguridad que ninguna. Lo que hace el cambio es que el camino ya no es silencioso: restablecer una contraseña bloquea al usuario real fuera de su propio buzón de correo, que se nota dentro de la hora, mientras que una descarga no deja nada atrás sino una línea de registro. Si ese comercio no es el que desea para una clave en particular, no cree la clave: las claves de gestión no tienen alcances por fuente. Utilice una conexión Agentic Inbox OAuth para un buzón de correo verificado a través del correo electrónico.

Las claves de gestión no caducan. Diez claves en vivo por cuenta, que es un techo en lugar de una cuota, por lo que nombrarlas por script o por máquina por lo que revocar una es una decisión obvia.

Cambiar la contraseña de la cuenta revoca cada clave, en una rotación de rutina tanto como en una recuperación. Nadie puede decirles a esos dos separados en el momento en que escriben una nueva contraseña, por lo que la respuesta segura no depende de saber cuál era. Planea para ello: un guión de larga duración debe fallar en voz alta en un 401 en lugar de volver a entrar, y quien rota la contraseña miente una nueva clave después. Enviamos un correo electrónico al titular de la cuenta cuando se crea una clave, y una vez más cuando un cambio de contraseña los revoca, por lo que una clave hecha por otra persona no pasa desapercibida.

API de gestión y límites de tarifas de exportación

Dos contadores, ambos por cuenta en lugar de por llave, por lo que la rotación de una llave no los reajusta:

• 120 escribe cada 5 minutos a través de dominios, buzones y alias. Las lecturas no se cuentan, por lo que la votación de un dominio hasta que verifica es libre. Moving diez dominios y treinta buzones cuestan bien menos de cien escritos en total, por lo que el trabajo a granel normal no alcanza esto.
• 30 buzón exporta una hora. Un flujo de exportación cada mensaje en el buzón de correo, que es la cosa más cara que esta API puede ser pedido para hacer.

Sobre cualquiera de los que tengas 429 con { "error": { "code": "rate_limited" } } y a Retry-After en segundos. Esperar tanto tiempo en lugar de retratar inmediatamente: golpear repetidamente el límite alarga la pausa. Si un trabajo legítimo necesita más espacio, escríbanos en lugar de trabajar en torno a él; preferiríamos elevar el número que averiguarlo de un proyecto de ley.

Migrar varios dominios a la vez

El orden que funciona: POST /domains para cada nombre, publicar los registros que devuelve, encuesta GET /domains hasta que cada uno sea verificado, entonces POST /mailboxes por dirección. El correo puede ser copiado desde el antiguo host antes de la recortada MX, ya que un dominio sólo necesita su registro DKIM probado para POST /mailboxes/:id/import para correr, por lo que la migración y la conmutación no tienen que pasar el mismo día.

MCP

Agentic Inbox proporciona el punto final remoto del MCP https://franklymail.com/api/agent/mcp para la lectura de buzón, búsqueda y redacción de la preparación. Conectar a través de OAuth utilizando Guía de configuración. Domain provisioning y administración de buzón utilizan la gestión separada HTTP API documentada anteriormente.