Files and intake
Save email attachments to Files.
Promote inbound attachments into structured Files API records with folders, versions, collaborators, and source history.
Token first
Make sure the agent has these scopes.
Create a new token or update the agent's current token before trying the calls below.
Required token scopes
email:read
files:read
files:write
workflows:write
Outcome
What this gives you.
Attachments become durable workflow objects instead of getting buried inside message threads.
Use when
The operational shape.
- Invoices, signed documents, reports, or forms arrive by email.
- You need a file record tied to the source message and future updates.
- A downstream system or collaborator needs a signed download link.
API sequence
The calls to make.
01
Read the inbound message
GET/v1/messages/{message_id}/
Detect attachments and capture the source message ID.
02
Create or choose a folder
POST/v1/files/folders/
Organize files by vendor, client, project, or workflow.
Default example
Use this as the default shape for this step.
{
"name": "Vendor invoices",
"parent_id": "fld_accounts_payable"
}
03
Promote the attachment
POST/v1/files/
Create a file record with source_message_id and attachment metadata.
Default example
Use attachment promotion when the original email attachment should become a durable Files API object.
{
"folder_id": "fld_vendor_invoices",
"source_message_id": "msg_123",
"file_type": "document",
"name": "invoice-1042.pdf"
}
Append extracted rows
Use this when the attachment should feed a spreadsheet-like file instead of becoming a standalone document.
{
"rows": [
{
"Vendor": "Acme Supply",
"invoice_number": "1042",
"amount": "980.00"
}
],
"source_message_id": "msg_123"
}
Collaborator-visible file
Use this when people outside the agent need access through signed links or update notifications.
{
"folder_id": "fld_vendor_invoices",
"source_message_id": "msg_123",
"name": "invoice-1042.pdf",
"viewers": [
{
"type": "contact",
"id": "ctc_finance_lead"
}
],
"collaborators": [
{
"type": "contact",
"id": "ctc_vendor_owner"
}
]
}
04
Notify the next system
POST/v1/workflows/
Trigger review, extraction, or collaborator notification.
Default example
Use this as the default shape for this step.
{
"name": "Notify finance on new invoice file",
"trigger": "file_created",
"conditions": [
{"field": "folder_id", "op": "eq", "value": "fld_vendor_invoices"}
],
"writes": [
{"source": {"from": "event.payload"}, "target": {"type": "webhook", "url": "https://example.com/webhooks/invoices", "event_type": "workflow.file_created"}}
]
}
Create review task
Use this when a person should review the file before an external system receives it.
{
"name": "Review new invoice file",
"trigger": "file_created",
"conditions": [
{"field": "folder_id", "op": "eq", "value": "fld_vendor_invoices"}
],
"writes": [
{"source": {"from": "event.payload"}, "target": {"type": "task"}, "contract": {"required": ["summary"]}}
]
}
Controls
Review points.
- Message attachments are not Files records until promoted.
- Files keep versions, source message links, and collaborator metadata for later review.