Attachments

Prepare an attachment

Reserve storage and receive a short-lived upload instruction for one private file.

POST/api/v1/attachments

On this page

Authentication

Send a RouteKite API key as a Bearer token. This endpoint requires the email:send scope.

Required headers
Name	Type	Requirement	Description
`Authorization`	string	Required	Bearer API key with the required workspace scope.Example: `Bearer rk_your_key`
`Content-Type`	string	Required	Must be application/json.Example: `application/json`

Request fields
Name	Type	Requirement	Description
`filename`	string	Required	Original filename with a supported extension. Maximum 255 characters.Example: `invoice.pdf`
`content_type`	string	Required	The exact supported MIME type for the filename.Example: `application/pdf`
`size_bytes`	integer	Required	The exact positive byte size, up to 10,000,000 bytes.Example: `245800`
`sha256`	string	Required	The lowercase 64-character SHA-256 digest of the exact bytes.Example: `0123456789abcdef...`
`retention`	enum	Optional	auto_delete by default, or keep until explicit deletion.Example: `auto_delete`

Response fields
Name	Type	Requirement	Description
`id`	uuid	Always	The pending attachment ID.
`status`	enum	Always	pending after preparation.
`retention`	enum	Always	The selected retention mode.
`upload.method`	string	Always	Use this exact method.
`upload.url`	url	Always	Opaque upload destination.
`upload.headers`	object	Always	Use these exact headers.
`upload.expires_at`	date-time	Always	When the instruction expires.

The upload instruction expires after two hours. Upload the exact bytes described by the prepared metadata.

Status	Code	What it means	What to do
400	`INVALID_REQUEST`	Attachment metadata is invalid.	Confirm filename, type, size, and digest.
401	`UNAUTHORIZED`	The API key is invalid.	Check the Bearer header.
403	`FORBIDDEN`	The key cannot manage attachments.	Use email:send access.
404	`ATTACHMENT_NOT_FOUND`	The attachment is unavailable in this workspace.	Check the ID and workspace.
410	`ATTACHMENT_EXPIRED`	The upload instruction or file expired.	Prepare a new upload.
413	`STORAGE_LIMIT_EXCEEDED`	The account cannot reserve this file.	Remove unused files and retry.
422	`ATTACHMENT_TYPE_UNSUPPORTED`	The format is not accepted.	Use a supported format.
422	`ATTACHMENT_INVALID`	The bytes do not match the prepared metadata.	Recalculate and upload the exact file.
500 / 503	`ATTACHMENT_UNAVAILABLE`	The operation could not complete.	Retry after a short delay.