`file_email`

File an email. File one email from the owner's mailbox on the person's card and thread; it makes or joins a task. Filing it twice files it once.

Where it is

In the inbox area (filing an email on a person's card): open it with tools_for { area: "inbox" }, then call it with use_tool { name: "file_email", args }.

Does it need a yes?

Runs at once, no yes card: it changes only the office's own working state, and nothing reaches anyone. Here: files a received email on a task.

Inputs

Input	Type	Needed	About
`email`	string	yes	The other person's address. · up to 254 characters · format `^[^\s@<>",;]+@[^\s@<>",;]+\.[^\s@<>",;]+$`
`name`	string	no	1 to 120 characters
`direction`	"in" \| "out"	yes	in: they wrote to the owner. out: the owner wrote to them.
`source`	"inbox" \| "gmail_draft"	yes	inbox (in the mailbox) or gmail_draft (your draft).
`subject`	string	no	up to 300 characters
`text`	string	yes	The email's text, as it is. · 1 to 50,000 characters
`provider_id`	string	yes	The mailbox's own id for this email, so it is filed once. · 1 to 300 characters
`message_id`	string	no	Its Message-ID header. · up to 300 characters
`in_reply_to`	string	no	Its In-Reply-To header. · up to 300 characters
`references`	string	no	Its References header. · up to 2,000 characters
`link`	string	no	The https link that opens it in the mailbox. · up to 500 characters · format `^https:\/\/[^\s<>"]{3,}$`
`at`	string	no	When it was sent, ISO time with offset.
`department`	"sales" \| "service"	no	For a new task from an email in: sales or service.
`urgent`	boolean	no
`task`	integer	no	The task you hold that this email belongs to. · 1 or more
`run_id`	string	yes	The run_id from start. Pass it on every call: it keeps your task held. · 1 to 100 characters

Example

{
  "name": "file_email",
  "arguments": {
    "email": "ana@example.com",
    "direction": "in",
    "source": "inbox",
    "text": "Hi Ana, thanks for your message.",
    "provider_id": "provider id",
    "run_id": "the run_id from start"
  }
}

When it is refused

invalid: The input isn't right. The sentence names the field and the fix; nothing was done. Fix it and call again.
not_found: No such thing in this company (a task, file, person, record). Check the number or name, or list first.
not_allowed: Not without another step: the owner's yes, your own task held with pick_up, or a setting the owner turns on. The sentence says which.
taken: Someone else holds it (another AI on that task). Pick another task.
stale: It changed since you read it. Read it again and use the new version.
failed: On our side or a service's, never your input. Try again in a minute; if it keeps failing, call report_problem.