> ## Documentation Index > Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create an attachment upload URL > Create a short-lived upload URL and token that lets a remote client PUT one binary attachment without exposing the API key on the upload request. Requires `email.send` permission. ## OpenAPI ````yaml https://smtp.sendmux.ai/api/v1/openapi.json post /emails/attachment-uploads openapi: 3.1.0 info: title: Sendmux Sending API version: 1.0.0 description: >- Send emails programmatically via the Sendmux email infrastructure. Every response carries an `X-Request-Id` header; errors include a `retryable` flag. 429 and 503 responses include `Retry-After`. Mutating endpoints accept an `Idempotency-Key` header for safe retries. servers: - url: https://smtp.sendmux.ai/api/v1 description: Production security: - BearerAuth: [] paths: /emails/attachment-uploads: post: tags: - Attachments summary: Create an attachment upload URL description: >- Create a short-lived upload URL and token that lets a remote client PUT one binary attachment without exposing the API key on the upload request. Requires `email.send` permission. operationId: sendingCreateAttachmentUpload parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Optional client-generated key to make the request idempotent for 24 hours. Replays under the same key return the cached response; a reused key with a different body returns 409 idempotency_conflict. example: order-12345-2026-04-24 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AttachmentUploadIntentRequest' responses: '201': description: Attachment upload URL created headers: Location: description: Canonical URL for the temporary attachment upload intent. schema: type: string content: application/json: schema: $ref: '#/components/schemas/AttachmentUploadIntentResponse' '400': description: Malformed request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Idempotency conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: Attachment exceeds the upload size cap content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Attachment upload validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Attachment upload service temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: AttachmentUploadIntentRequest: type: object properties: filename: type: string minLength: 1 maxLength: 255 description: Filename to associate with the uploaded attachment. example: analysis.pdf content_type: type: string maxLength: 255 description: MIME type expected for the upload. example: application/pdf size_bytes: type: integer exclusiveMinimum: 0 description: Exact byte size that will be uploaded. example: 20480 sha256: type: string pattern: ^[a-f0-9]{64}$ description: Optional SHA-256 hex digest for the upload bytes. example: '0000000000000000000000000000000000000000000000000000000000000000' required: - filename - size_bytes additionalProperties: false AttachmentUploadIntentResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/AttachmentUploadIntentData' required: - data unevaluatedProperties: false ErrorResponse: type: object properties: ok: type: boolean enum: - false error: $ref: '#/components/schemas/ErrorDetail' meta: $ref: '#/components/schemas/Meta' required: - ok - error - meta additionalProperties: false SuccessEnvelope: type: object properties: ok: type: boolean enum: - true meta: $ref: '#/components/schemas/Meta' required: - ok - meta AttachmentUploadIntentData: type: object properties: upload_id: type: string pattern: ^upl_[a-z0-9]{24}$ description: Temporary upload intent ID. example: upl_tz4a98xxat96iws9zmbrgj3a upload_url: type: string format: uri description: Short-lived URL that accepts a binary PUT with the returned headers. example: >- https://smtp.sendmux.ai/api/v1/emails/attachment-uploads/upl_tz4a98xxat96iws9zmbrgj3a method: type: string enum: - PUT description: HTTP method for upload_url expires_at: type: string format: date-time description: ISO timestamp when the upload URL expires. example: '2026-07-07T08:15:00.000Z' max_size_bytes: type: integer description: Maximum upload size in bytes example: 18874368 headers: type: object additionalProperties: type: string description: Headers that must be sent with the PUT upload request. example: Content-Type: application/pdf Content-Length: '20480' X-Sendmux-Upload-Token: smx_upload_... required: - upload_id - upload_url - method - expires_at - max_size_bytes - headers additionalProperties: false ErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: validation_error message: type: string description: Human-readable error description param: type: string description: Parameter that caused the error doc_url: type: string format: uri description: Link to error documentation retryable: type: boolean description: >- True when the client may safely retry the same request. 429 and 5xx default true; 4xx default false. errors: type: array items: $ref: '#/components/schemas/ErrorIssue' description: Accumulated per-field issues (validation errors) required: - code - message - retryable additionalProperties: false Meta: type: object properties: request_id: type: string description: Unique request identifier example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx required: - request_id additionalProperties: false ErrorIssue: type: object properties: field: type: string description: Dot-path to the failing field example: to.email code: type: string description: Issue code from the validator example: invalid_string message: type: string description: Human-readable issue message required: - field - code - message additionalProperties: false securitySchemes: BearerAuth: type: http scheme: bearer description: Sendmux API key (smx_...) ````