File Cache

Upload a file once, reference it by id in many sends. R2-backed, 25 MB per file.

Upload a file

POST /api/files

Scopes: files:write

Field	Type	Required	Description
`filename`	string	Yes	Display name for the attachment.
`content`	string	Yes	Base64-encoded bytes (or data URI).
`contentType`	string	No	MIME type. Auto-detected from extension if omitted.
`expiresAt`	ISO-8601	No	Auto-purge after this time.

Example

upload

curl -X POST https://api.mailgrid.space/api/files \
  -H "Authorization: Bearer $MAILGRID_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "logo.png",
    "content":  "iVBORw0KGgoAAAANSUhEUgAA...",
    "contentType": "image/png"
  }'

Response

201 Created

{
  "success": true,
  "data": {
    "id":           "a1b2c3d4-...",
    "filename":     "logo.png",
    "contentType":  "image/png",
    "sizeBytes":    8421,
    "r2Key":        "tenants/.../files/a1b2c3d4-...",
    "createdAt":    "2026-05-16T05:00:00Z"
  }
}

Reference in a send

send with fileId

{
  "from": "hello@yourdomain.com",
  "to":   "user@example.com",
  "subject": "Heres the logo",
  "html": "See attached.",
  "attachments": [
    { "fileId": "a1b2c3d4-..." }
  ]
}

List files

GET /api/files

Get file metadata

GET /api/files/:id

Delete a file

DELETE /api/files/:id

Removes the R2 object and the metadata row.

SES raw MIME path

When any attachment is present (inline or fileId), Mailgrid switches from SES Simple content to Raw MIME. We hand-construct multipart/mixed with multipart/alternative bodies + each attachment as base64-encoded part.