--- title: "Create File" method: POST path: "/v0/inboxes/{inbox_id}/files" tags: ["inboxes > files"] --- # Create File `POST /v0/inboxes/{inbox_id}/files` ## Request - Base URL: `https://api.agentmail.to` - URL: `https://api.agentmail.to/v0/inboxes/{inbox_id}/files` - Auth: HTTP bearer Starts an upload: creates a pending file at `path` and returns an `upload` to `PUT` its bytes to. The bytes go straight to storage, not through the API. Then call Complete File to make the file `ready`. Retry-safe: sending the identical request again (same `path`, `size`, `sha256`, `content_type` and `expires_at`) returns the existing file with `200` instead of `201`: a pending one with a fresh `upload`, or a `ready` one without. If its bytes were uploaded but the upload was never completed, it is completed then. A different request at a path whose file is still pending and has no bytes replaces that file; at any other taken path it returns `409`. The file counts against the organization's Drive quota from creation, pending or not: 1 GiB and 10,000 files by default. A file that doesn't fit returns `403` with code `limit_exceeded`. Deleting a file frees its space within seconds. Expired files count until a create needs their space: a create that doesn't fit first gives back what expired files hold, a batch at a time, so retry a refusal while many expired files remain. Requires the `file_create` permission, which an unverified organization's keys don't have at any scope until it completes agent verification. A key without `file_read` can still create files, but gets the plain `409` at any taken path, even for an identical request at a file it didn't create. Agent Drive is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet in EU production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`. ## Path parameters - `inbox_id` string, required: The ID of the inbox. ## Request body - object - `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. - `size` integer, required: Size of the file in bytes. At most 104,857,600 (100 MiB). - `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. - `content_type` string: The file's MIME type, such as `application/pdf`. Defaults to `application/octet-stream`. - `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. ## Response `200` Response with status 200 - FilesCreateFileResponse: The created file. A pending file carries `upload`; a create that returns an existing `ready` file does not. - `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. - `upload` FilesFileUpload: Where to upload a pending file's bytes: one HTTP `PUT` to `url` with exactly `headers` and the file's bytes as the body. Every header is signed, so S3 refuses the upload if any is missing or different, and refuses bytes whose size or SHA-256 doesn't match the file. Then call Complete File. - `method` 'PUT', required: Always `PUT`. - `url` string, required: The presigned S3 URL. No API key is needed to use it. - `headers` object, required: The headers to send with the `PUT`, exactly as given. - `expires_at` string, date-time, required: When `url` stops working, at most an hour after it was issued. Send the identical create request again for a fresh one. ## 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 - `409`: Error response with status 409 ## Changes - **2026-10-16** `3f5c7830c952`: 1 info - endpoint added [Operation history](https://skmtc.dev/agentmail-to/apis/api/changes/v0/inboxes/:inbox_id/files/post.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)