Pular para o conteúdo

Guarde e anexe arquivos

Envie um arquivo uma vez e anexe-o pelo id a rascunhos, respostas e e-mails transacionais. Você também pode listar e excluir arquivos guardados.

Guarde um arquivo pequeno

Envie os bytes do arquivo em base64 em content, junto com name e type. Este exemplo guarda um arquivo de texto curto:

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);

A resposta é o arquivo guardado: id, name, type, sizeBytes, sha256, quem guardou e expiresAt. Compare o sha256 com o hash do seu arquivo para saber se ele chegou inteiro. Guardamos o tipo que você informar e nunca lemos os bytes para conferir. Se você não informar, fica application/octet-stream.

No MCP, uma chamada inteira tem no máximo 1 MB, uns 750 KB de arquivo. Para um arquivo maior, use uma URL de envio.

Envie um arquivo maior

files.createUpload recebe name e type do arquivo e responde uma url. Envie os bytes para ela com PUT, por um shell ou pelo seu programa. Não mande sua chave de API no PUT. A URL funciona uma vez, por 15 minutos, e aceita até 15 MB. Mantenha-a em segredo.

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 }

Num shell, curl -T invoice-1042.pdf "$URL" envia o arquivo. O PUT responde o arquivo guardado, no mesmo formato que files.create responde.

Se a resposta do PUT se perder, tente de novo com a mesma URL enquanto ela funcionar. Uma URL já usada devolve o mesmo arquivo, sem ler os bytes outra vez. A chave e quem a criou ainda precisam ter permissão, mesmo numa nova tentativa. Se a URL expirou, peça outra. Repetir o pedido com o mesmo Idempotency-Key devolve url: null, então use outra chave para receber uma URL nova.

Anexe arquivos a um e-mail

Passe até 10 ids de arquivos em fileIds ao criar ou alterar um rascunho (drafts.create, drafts.update, drafts.reply), responder a uma mensagem na hora (messages.reply) ou enviar um e-mail transacional (transactional.send). Em drafts.update, fileIds substitui a lista do rascunho, e [] remove todos os arquivos.

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);

Arquivos anexados saem só por uma caixa conectada ao servidor do próprio provedor. Uma inbox de agente, um endereço de remetente ou uma caixa que envia pelos nossos servidores responde 409 serverErrors.filesNotFromOurServers (e drafts.preview lista files_not_from_our_servers). O Microsoft 365 aceita até 4 MB de MIME em base64 no total, e o Gmail e o SMTP aceitam até 25 MB de MIME bruto; acima disso, o envio responde 409 serverErrors.messageTooLargeForMailbox (e drafts.preview lista message_too_large). Quando um rascunho com arquivos vai para um endereço que ainda não escreveu para o workspace, drafts.preview também traz files_on_first_email em warnings.

Os rascunhos e as prévias listam os arquivos anexados em files (id, name, type, sizeBytes, sha256). Os envios guardam esses mesmos dados em files com fileId, que passa a ser null quando o arquivo guardado é excluído ou expira.

Encontre e exclua arquivos

files.list lista os arquivos do workspace, do mais recente ao mais antigo, uma página por vez. files.get lê um, e files.remove exclui um na hora, com os bytes (409 serverErrors.filePinned enquanto um rascunho não enviado ou um e-mail na fila para sair o usa). Nenhuma dessas chamadas devolve os 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 });
}

Qualquer chave com operate, send ou transactional pode guardar arquivos. Uma chave com operate e sem lista de leitura vê todos os arquivos do workspace. Uma chave com lista de leitura, ou sem operate, vê, anexa e exclui só os arquivos que ela mesma guardou. Um arquivo de outro workspace responde 404.

Limites e por quanto tempo os arquivos ficam

Um arquivo pode ter até 15 MB, e um e-mail pode levar até 10 arquivos. Um arquivo maior responde 413, e um vazio responde 400.

Um workspace guarda até 1.024 MB de arquivos no total. Cada URL de envio ainda não usada reserva 15 MB desse total até ser usada ou expirar. Acima do limite, guardar um arquivo ou pedir uma URL responde 409 serverErrors.fileStorageFull, com used e limit em bytes. Exclua os arquivos de que você não precisa mais para abrir espaço.

Enquanto um rascunho não enviado ou um e-mail agendado, reservado ou saindo usa um arquivo, expiresAt vem como null e o arquivo não pode ser excluído nem limpo. Fora isso, ele é excluído 7 dias depois de guardado ou do último uso, ou antes, quando você o exclui. Ler ou listar o arquivo não muda esse prazo. Depois do expiresAt, ele responde 404 e deixa de contar no limite.

Um workspace pode guardar arquivos e pedir URLs de envio 300 vezes por hora. Acima disso, a resposta é 429 com Retry-After.