Saltar al contenido

Guarda y adjunta archivos

Sube un archivo una vez y adjúntalo por su id a borradores, respuestas y correos transaccionales. También puedes listar y eliminar archivos guardados.

Guarda un archivo pequeño

Envía los bytes del archivo en base64 en content, junto con name y type. Este ejemplo guarda un archivo de texto corto:

const file = await colding.files.create({
  name: "price-list.txt",
  type: "text/plain",
  content: btoa("Hello Ana, here is our price list.\n"),
});
console.log(file.id, file.sha256);

La respuesta es el archivo guardado: id, name, type, sizeBytes, sha256, quién lo guardó y expiresAt. Compara el sha256 con el hash de tu archivo para saber que llegó entero. Guardamos el tipo que indiques y nunca leemos los bytes para comprobarlo. Si no lo indicas, queda application/octet-stream.

En MCP, una llamada completa tiene un tope de 1 MB, unos 750 KB de archivo. Para un archivo más grande, usa una URL de subida.

Sube un archivo más grande

files.createUpload recibe el name y el type del archivo y responde una url. Envía los bytes a esa URL con PUT, desde una terminal o desde tu programa. No envíes tu clave de API con el PUT. La URL funciona una vez, durante 15 minutos, y acepta hasta 15 MB. Guárdala en secreto.

const upload = await colding.files.createUpload({ name: file.name, type: file.type });
if (!upload.url) throw new Error("Ask for another upload URL with a new Idempotency-Key.");

const response = await fetch(upload.url, { method: "PUT", body: file });
if (!response.ok) {
  const wait = response.headers.get("Retry-After");
  throw new Error(
    wait
      ? `Upload paused. Wait ${wait} seconds, then retry the same URL.`
      : `Upload failed (${response.status}). Read the answer before you retry.`,
  );
}
console.log(await response.json()); // { data: the stored file, with its id and sha256 }

En una terminal, curl -T invoice-1042.pdf "$URL" envía el archivo. El PUT devuelve el archivo guardado, con la misma forma que devuelve files.create.

Si pierdes la respuesta del PUT, reintenta con la misma URL mientras funcione. Una URL ya usada devuelve el mismo archivo, sin volver a leer los bytes. La clave y quien la creó deben conservar el permiso, también en los reintentos. Si la URL venció, pide otra. Repetir la petición con el mismo Idempotency-Key devuelve url: null, así que usa otra clave para obtener una URL nueva.

Adjunta archivos a un correo

Pasa hasta 10 ids de archivos en fileIds al crear o cambiar un borrador (drafts.create, drafts.update, drafts.reply), responder a un mensaje al momento (messages.reply) o enviar un correo transaccional (transactional.send). En drafts.update, fileIds reemplaza la lista del borrador, y [] quita todos los archivos.

const draft = await colding.drafts.create({
  mailboxId: "11111111-1111-4111-8111-111111111111",
  to: "[email protected]",
  subject: "Our price list",
  bodyText: "Here is the price list you asked for.",
  fileIds: [fileId],
});
console.log(draft.files);

const reply = await colding.messages.reply({
  messageId: "22222222-2222-4222-8222-222222222222",
  bodyText: "Here is the signed copy.",
  fileIds: [fileId],
  intentKey: "reply-signed-copy-1",
});
console.log(reply.files);

const receipt = await colding.transactional.send({
  mailboxId: "33333333-3333-4333-8333-333333333333",
  to: "[email protected]",
  subject: "Invoice 1042",
  bodyText: "Thank you for your payment. Your invoice is attached.",
  fileIds: [fileId],
  intentKey: "invoice-1042",
});
console.log(receipt.files);

Los archivos adjuntos salen solo desde un buzón conectado a su propio servidor de correo. Una bandeja de entrada de agente, una dirección de remitente o un buzón que envía por nuestros servidores responde 409 serverErrors.filesNotFromOurServers (y drafts.preview incluye files_not_from_our_servers). Microsoft 365 acepta hasta 4 MB de MIME en base64 en total, y Gmail y SMTP aceptan hasta 25 MB de MIME bruto; por encima de eso, el envío responde 409 serverErrors.messageTooLargeForMailbox (y drafts.preview incluye message_too_large). Cuando un borrador con archivos va a una dirección que todavía no escribió al workspace, drafts.preview también incluye files_on_first_email en warnings.

Los borradores y las vistas previas listan los archivos adjuntos en files (id, name, type, sizeBytes, sha256). Los envíos guardan esos mismos datos en files con fileId, que pasa a ser null cuando el archivo guardado se elimina o vence.

Encuentra y elimina archivos

files.list lista los archivos del workspace, del más reciente al más antiguo, una página a la vez. files.get lee uno, y files.remove elimina uno al momento, con sus bytes (409 serverErrors.filePinned mientras lo use un borrador sin enviar o un correo pendiente de salir). Ninguna de estas llamadas devuelve los bytes.

const page = await colding.files.list({ limit: 50 });
for (const file of page.items) console.log(file.name, file.sizeBytes, file.expiresAt);

const [newest] = page.items;
if (newest) {
  const file = await colding.files.get({ fileId: newest.id });
  console.log(file.sha256);
  await colding.files.remove({ fileId: file.id });
}

Cualquier clave con operate, send o transactional puede guardar archivos. Una clave con operate y sin lista de lectura ve todos los archivos del workspace. Una clave con lista de lectura, o sin operate, ve, adjunta y elimina solo los archivos que ella misma guardó. Un archivo de otro workspace responde 404.

Límites y cuánto tiempo se guardan los archivos

Un archivo puede tener hasta 15 MB, y un correo puede llevar hasta 10 archivos. Un archivo más grande responde 413, y uno vacío responde 400.

Un workspace guarda hasta 1024 MB de archivos en total. Cada URL de subida que todavía no se usó reserva 15 MB de ese total hasta que se use o venza. Por encima del límite, guardar un archivo o pedir una URL responde 409 serverErrors.fileStorageFull, con used y limit en bytes. Elimina los archivos que ya no necesitas para hacer espacio.

Mientras un borrador sin enviar o un correo programado, reservado o saliendo use un archivo, expiresAt viene en null y el archivo no se puede eliminar ni limpiar. De lo contrario, se elimina 7 días después de guardarse o de su último uso, o antes, cuando lo eliminas. Leerlo o listarlo no cambia ese plazo. Cuando pasa su expiresAt, responde 404 y deja de contar para el límite.

Un workspace puede guardar archivos y pedir URLs de subida 300 veces por hora. Por encima de eso, responde 429 con Retry-After.