---
title: "Get File"
method: GET
path: "/v0/inboxes/{inbox_id}/files/{file_id}"
tags: ["inboxes > files"]
---

# Get File

`GET /v0/inboxes/{inbox_id}/files/{file_id}`

## Request

- Base URL: `https://api.agentmail.to`
- URL: `https://api.agentmail.to/v0/inboxes/{inbox_id}/files/{file_id}`
- Auth: HTTP bearer

Gets a file. A `ready` file comes with a fresh `download_url`, valid for up to an hour.

A get reads the region that serves the request, so for about a second after a delete it can still return
the deleted file. A file that has expired returns `404` at once.

Requires the `file_read` permission.

## Path parameters

- `inbox_id` string, required: The ID of the inbox.
- `file_id` string, required: ID of the file. A UUID.

## Response `200`

Response with status 200

- FilesFile: A file. A `ready` file returned to a caller with the `file_read` permission carries a signed `download_url`.
  - `file_id` string, required: ID of the file. A UUID.
  - `inbox_id` string, required: The ID of the inbox.
  - `email` string, required: Email address of the inbox.
  - `path` string, required: Where the file lives in its inbox's drive, such as `reports/q3.pdf`. Unique within the inbox. Segments are separated by `/`, with no leading or trailing `/`, no empty, `.` or `..` segment, no `\` and no control or invisible characters. At most 1,024 bytes, and at most 255 bytes per segment. Stored in Unicode NFC, so two spellings of one name are one path. Case is kept.
  - `name` string, required: The path's last segment. A download saves under this name.
  - `size` integer, required: Size of the file in bytes. At most 104,857,600 (100 MiB).
  - `content_type` string, required: The file's MIME type, such as `application/pdf`. Defaults to `application/octet-stream`.
  - `sha256` string, required: The base64 encoding of the file's 32-byte SHA-256 digest, as S3's `x-amz-checksum-sha256` takes it (44 characters, ending in `=`). S3 refuses an upload whose bytes don't match.
  - `status` 'pending' | 'ready', required: `pending` until its bytes are uploaded and the upload is completed, then `ready`. Only a `ready` file has a download URL. A pending file is deleted if it isn't completed within a day.
  - `created_at` string, date-time, required: When the file was created.
  - `updated_at` string, date-time, required: When the file last changed, such as when its upload was completed.
  - `expires_at` string, date-time: When the file expires. After it, the file is gone from get and list and its path is free; its bytes are deleted soon after. Absent for a file that never expires.
  - `download_url` string: A signed URL that downloads the file's bytes, named by `name`. No API key is needed to use it, so treat it as a secret. It works until `download_expires_at`, at most an hour, even after the file is deleted. Get the file again for a fresh one.
  - `download_expires_at` string, date-time: When `download_url` stops working. Never after the file's own expiry.

## Other responses

- `400`: Error response with status 400
- `403`: `code` says why: `forbidden` when the organization hasn't joined AgentMail Labs; `missing_permission` when the credential lacks the file permission the endpoint needs, including `file_create` in an organization that hasn't completed agent verification, and every file permission for an organization- or pod-scoped key under a content-access policy; `account_suspended`, `pod_suspended` or `inbox_suspended` when the organization, pod or inbox is suspended; and, for Create File only, `limit_exceeded` when the file doesn't fit the organization's Drive quota.
- `404`: Error response with status 404

## Changes

- **2026-10-16** `3f5c7830c952`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentmail-to/apis/api/changes/v0/inboxes/:inbox_id/files/:file_id/get.md)

---

[API](https://skmtc.dev/agentmail-to/apis/api.md) - [All operations](https://skmtc.dev/agentmail-to/apis/api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentmail-to/apis/api/revisions/a9792efe7bdf?raw)