Base de conocimiento

API REST

Una API HTTP documentada, con claves que se pueden emitir, acotar por scopes y revocar.

Detalles

Activa, en todas partes. La API ofrece 104 operaciones documentadas repartidas en 68 rutas (correos, hilos, borradores, etiquetas, contactos, audiencias, dominios, plantillas, reglas, roles, miembros, configuración, calendario, seguimiento, webhooks y la cuenta) detrás de un documento OpenAPI 3.1 versionado en el repositorio que puedes leer sin clave en GET /openapi.json. El acceso lo decide la clave de espacio de trabajo que emites en Configuración.
La durabilidad que antes faltaba ya está hecha. Un envío escribe una fila antes de despachar nada, con un id público con la forma msg_ seguido de 24 caracteres hexadecimales, y GET /emails/{id} lo resuelve, junto con /events para el rastro por destinatario y /tracking para aperturas y clics. Una Idempotency-Key de entre 1 y 255 caracteres se reclama contra un índice único sobre la clave y tu clave de API juntas, así que un reintento tras un tiempo de espera agotado devuelve el primer resultado con Idempotency-Replayed: true en lugar de enviar dos veces. Un envío con clave responde 200 una vez asentado y 202 mientras sigue en cola o programado.
Las claves se emiten, se acotan, se rotan y se revocan en Configuración → Claves de API. Todas las claves que emite la consola son oe_live_. El prefijo oe_test_ lo entienden el verificador y la ruta de envío, donde un envío en modo de prueba se registra y se responde como enviado sin llegar nunca a un transporte, pero todavía nada puede emitir una, y ofrecer la opción antes de que el transporte inocuo esté por encima del Durable Object te daría una clave de prueba que entrega de verdad. Una clave lleva un alcance de envío de hasta 25 dominios completos y 50 direcciones sueltas, donde un dominio completo cubre también las direcciones que se le añadan después, una caducidad opcional de entre 1 y 3650 días y, opcionalmente, un rol. El rol es un techo y no una segunda concesión: GET /ping devuelve tanto los scopes de la clave como los scopes que el rol le ha dejado, así que un 403 por un scope que tu clave nombra claramente tiene una causa visible. Revocar es una actualización y no un borrado, de modo que a una llamada posterior se le responde revoked_api_key en lugar de fallar sin más la autenticación. Rotar conserva todo de la clave salvo el secreto: el id, los scopes, el alcance de envío y el historial de solicitudes continúan, el secreto antiguo muere en el instante en que se emite el nuevo, y una clave con keys:write puede rotarse a sí misma por la API. Las mismas acciones de listar, rotar, revocar y activar están en el servidor MCP para cualquiera cuyo rol pueda gestionar claves.
Lo que falta de verdad: la API no tiene un endpoint de subida propio. Los adjuntos en línea van como base64 con un tope total de 5 MB, y un archivo mayor se envía nombrando por su id un archivo que ya está en el espacio de trabajo, que viaja como enlace de descarga. Los rebotes se gestionan en el buzón y no en el registro de envíos: un informe de entrega se analiza, se empareja con el original por Message-ID, se etiqueta en el hilo y se emite como webhook email.bounced, pero nada se escribe de vuelta en la fila de envío, cuyo estado no tiene un valor de rebote, así que a través de GET /emails un mensaje rebotado sigue figurando como enviado. El correo enviado desde el redactor de la aplicación tampoco aparece en GET /emails, porque el redactor no escribe a través de esa misma ruta de envío.