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": 1073741824,
    "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:

{
  "url": "https://storage.molted.email/tenants/tenant-abc/attachments/2026/03/550e8400...?X-Amz-Signature=..."
}

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: 1073741824 bytes, limit: 1073741824 bytes."
}

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