Handle email attachments as bounded untrusted files
Inspect metadata, download bytes deliberately and keep attachment content out of automatic tool execution.
Plan email retention around content expiry and durable accounting
Understand what expires, what remains and how storage settings affect an agent’s ability to revisit messages.
Distinguish resources from retained content
An email agent may retain message bodies, raw source, draft content, attachments and derived local records. Those data classes do not all share the same lifetime. Lupin’s retained-content policy covers message and draft content, raw messages and binary attachments, alongside other supported content types. Resource metadata, database overhead and durable reconciliation or accounting records have separate purposes. Do not describe deleting a message body as erasing every trace of an operation, and do not promise indefinite access merely because a message ID still appears in your application’s case record.
Read the active workspace policy
GET /v0/billing/storage reports stored, reserved, deleting and available bytes, the byte limit, retention days and policy activation information. Use an organization key with the required read permission; project and inbox keys cannot manage retained-content settings. Inspect enforced and historical-content expiry information before drawing conclusions about old mail. Legacy compatibility policy can differ from newly enrolled workspace policy. A plan name alone is insufficient to infer exactly when a particular historical body will expire. Build your interface around the returned policy state and actual content availability.
Change retention with explicit intent
POST /v0/billing/storage/retention accepts retention_days within the current plan maximum. Changes normally apply to future content. Applying expiry to existing content requires apply_to_existing and explicit confirmed true because that changes the future availability of retained records. The effective date starts a full new retention window rather than deleting old content immediately. An agent should not shorten retention simply to clear a storage error without owner review. Expiry is permanent once content is deleted, and extending the window later cannot restore bytes that are already gone.
Handle expired content as a real limitation
If a body or attachment is expired, return a clear content-unavailable state and avoid presenting an empty string as a successful summary of the original message. The content storage layer can expose content_expired and a content_retention_expired error where appropriate. Preserve whatever non-sensitive references your business workflow needs, but do not reconstruct missing correspondence from an earlier model guess and label it authoritative. If your own system stores summaries or downloaded files, give them an explicit retention policy too; Lupin’s expiry cannot delete copies your application created elsewhere.
Keep capacity and accounting separate
Storage has a hard cap and storage overages are currently unavailable. Reserved and deletion-pending bytes can still reduce available capacity, so deleting one record does not necessarily mean new content can be accepted immediately. Usage ledger entries remain after related email resources are deleted and are not a retained-content backup. Track storage availability, processing backlog and expired-source references separately. Your next step is to read the storage overview and document which data your application copies, why it needs those copies and how each copy expires.
A concrete operational check
Before promising that an agent can revisit a month-old attachment, compare the active retention window with the work item’s age and try the authorized attachment read. If the file is unavailable, ask for a new document through the approved workflow rather than rerunning a parser against stale local assumptions. That makes the limitation visible at the point where it matters.
Sources & verification
Reviewed against checked-in Lupin API handlers and documentation. Example requests were not executed against live providers.
- Lupin billing retained-content policy Checked 2026-11-05
- Lupin attachment storage Checked 2026-11-05
- Lupin durable usage ledger Checked 2026-11-05
Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.