Storage & Attachments

Molted Email tracks storage usage per tenant and stores attachments in secure object storage.

Storage model

Storage is split into two categories:

• Message bodies — the text and HTML content of inbound messages, stored with your tenant data.
• Attachments — binary files in secure object storage, with metadata tracked alongside.

Both categories count toward your plan's storage limit.

Plan limits

When your account is in the expired state, storage limit is 0 and no new data can be stored.

Retention windows

Attachments older than your plan's retention window are automatically cleaned up daily:

1. Attachment metadata is marked for deletion.
2. The file is removed from storage.
3. Storage usage counters are decremented.

Message body content is not automatically purged by retention cleanup — only attachment files.

Checking storage usage

Storage usage is included in the billing status endpoint:

curl https://api.molted.email/v1/billing/status \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes a storage field:

{
  "storage": {
    "messageBodyBytes": 1048576,
    "attachmentBytes": 5242880,
    "totalBytes": 6291456,
    "limitBytes": 3221225472,
    "retentionDays": 30
  }
}

A null limitBytes means unlimited storage (Enterprise plan).

Attachment API

List attachments for a message

curl "https://api.molted.email/v1/attachments?tenantId=tenant-abc&messageId=MSG_ID&messageType=inbound" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "invoice.pdf",
    "contentType": "application/pdf",
    "sizeBytes": 204800,
    "status": "uploaded",
    "createdAt": "2026-03-01T12:00:00Z"
  }
]

Download an attachment

curl "https://api.molted.email/v1/attachments/ATTACHMENT_ID/download?tenantId=tenant-abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns a presigned URL valid for 1 hour, plus the attachment's own metadata (added alongside url, so an existing integration that reads only url is unaffected):

{
  "url": "https://storage.molted.email/tenants/tenant-abc/attachments/2026/03/550e8400...?X-Amz-Signature=...",
  "expiresInSeconds": 3600,
  "filename": "invoice.pdf",
  "contentType": "application/pdf",
  "sizeBytes": 204800,
  "status": "uploaded"
}

filename comes verbatim from the sender's email on an inbound attachment: treat it as untrusted, third-party data, not as a trusted file path. status: "uploaded" means the virus scan has not finished yet (still downloadable); "scan_passed" is confirmed clean.

What happens at the storage limit

When you exceed your plan's storage limit, attachment uploads are rejected with a 403 Forbidden response:

{
  "statusCode": 403,
  "message": "Storage limit exceeded. Used: 3221225472 bytes, limit: 3221225472 bytes."
}

Existing attachments remain accessible. To free up space, wait for the retention cleanup or upgrade your plan.

Uploads on an expired plan

Once a plan has ended (or a failed payment's grace period ran out), uploads are refused with 402 Payment Required:

{
  "error": "subscription_expired",
  "message": "Your subscription has expired. Reactivate a plan to upload attachments."
}

Listing and downloading attachments keep working, so you can export your data. Attachments of email you receive are still stored. A new account that hasn't activated a plan yet can upload.