Moving files between services
Attach a file from one connected service to another without downloading it: how file references work and where the file is while it moves.
Some jobs need a file to go from one connected service to another: an email filed on a Jira issue, for example. Without a connector that means downloading the file and uploading it again by hand. With DataToRAG it is one tool call, and the file's content never passes through the conversation.
File references
A tool that takes a file takes a file reference. Most references are a small object that says where the file lives in one of your connected services: a name for the file, not the file. A content reference is the exception: it carries a file your agent already holds, in the call itself.
| Reference | Fields | The file |
|---|---|---|
gmail_message |
message_id, optional account |
An email as its original .eml file, exactly as Gmail returns it |
gmail_attachment |
message_id, part_id, optional account |
One attachment of an email, under the sender's file name and type |
drive_file |
file_id, optional account |
A Google Drive file as stored, under its Drive name |
drive_export |
file_id, format, optional account |
A Google Docs, Sheets or Slides file exported to a format, named with its extension |
content |
name, base64, optional mime_type |
A file your agent already holds, carried in the call as base64, at most 1 MB |
upload |
upload_id |
A file you sent from your computer through an upload link, at most 25 MB |
A Google Docs, Sheets or Slides file has no stored file to send as it is, so as a drive_file it is refused with the drive_export reference to use instead. The formats are:
| A Google file | Exports as |
|---|---|
| Docs | pdf, docx, txt, md, html, rtf, odt, epub |
| Sheets | pdf, xlsx, csv and tsv (the first tab), html (a zip, one page per tab), ods |
| Slides | pdf, pptx, txt (the slides' text), odp |
A folder, a shortcut and a file in Trash are refused before anything is read. Google also limits how large an export can be; an export over that limit is refused as too large.
A reference can only be resolved for you, with your own connection to the service it names. account picks which connected Google account holds the message or file when you have more than one. With drive_upload_file, that makes a reference the way to copy a file from one account's Drive into another's.
An attachment is named by its part id, not its attachment id. Gmail issues a new attachment id every time a message is read, so an id copied out of one read does not match the next; the part id ("1", "0.1") is the attachment's place in the message and stays the same. gmail_read lists each attachment with its partId.
Tools that take a file
| Tool | What it does |
|---|---|
jira_add_attachment |
Adds the referenced file to a Jira issue as an attachment |
file_download_link |
Makes a link that saves the referenced file to your own computer, once |
drive_upload_file |
Puts the referenced file in Google Drive under its own name, and checks what Drive stored |
gmail_send, gmail_create_draft, gmail_reply, gmail_forward, gmail_update_draft |
Attach referenced files to an email, beside Drive files |
{
"issue_key": "PROJ-123",
"file": { "type": "gmail_message", "message_id": "<message id>" }
}
One attachment of that message, by its part id:
{
"issue_key": "PROJ-123",
"file": { "type": "gmail_attachment", "message_id": "<message id>", "part_id": "1" }
}
Each call moves one file. To attach three PDFs from one email, make three calls, one part id each.
Sending a file you have
When the file is already in the conversation, for example an image or a PDF you shared with your agent, a content reference carries it to drive_upload_file or jira_add_attachment directly:
{
"issue_key": "PROJ-123",
"file": { "type": "content", "name": "screenshot.png", "mime_type": "image/png", "base64": "<base64>" }
}
base64is the file in standard base64, as one unbroken string. Base64 broken across lines, or in the URL-safe alphabet, is refused rather than decoded into a damaged file.- The file can be at most 1 MB. For a larger file, or one your agent does not hold, use an upload link.
mime_typeis optional. Without it, the type comes from the name's extension.- A
contentreference takes noaccount, because the file comes with the call.
The receipt is the same as for any other reference: the SHA-256 and byte count of what DataToRAG received and handed on, and, for Drive, whether what Drive stored matches it.
A content reference cannot be used in the DataToRAG dashboard agent, and a download link cannot be made from one: the file is already on your side.
Uploading a file from your computer
When the file is on your computer, file_upload_link makes a link that takes it, so the file never passes through the conversation.
Open the link in a browser and it shows a page with one place to choose or drop the file and an Upload button. When the file has arrived, the page shows its size and SHA-256 and the reference to paste back into your conversation. It works on a phone too.
From a terminal, the answer also carries a one-line command that sends the file:
curl -fsS -T ./report.pdf "https://datatorag.com/files/u/<token>/"
The trailing slash lets the file keep its own name. Sending it answers a receipt with the file's name, size and SHA-256, and a reference:
{ "type": "upload", "upload_id": "<id>" }
Pass that reference as the file of drive_upload_file or jira_add_attachment, or as an entry of an email's attachments.
- The link takes one file, once, and stops working ten minutes after it is made.
- The file can be at most 25 MB.
- The uploaded file is kept for ten minutes after it arrives, for one call. After that it is gone, and you upload it again.
- If the call stops before anything is sent on (the service is busy, or another reference in the same email is wrong), the uploaded file is kept and the reference still works. Once the call reaches Drive, Jira or Gmail, the file is used, even if that service then says no (a folder id that is not a folder, an issue you cannot see): upload it again.
- You can have three upload links or uploaded files waiting at a time.
- An upload link, like a download link, is for you: a call that carries one is refused, and the link is canceled.
Attaching files to an email
The tools that write an email take attachments: up to ten entries, 25 MB together. An entry can be a Drive file id, as before, or a file reference of any type, and one email can carry several:
{
"to": "[email protected]",
"subject": "The files you asked for",
"body": "Both attached.",
"attachments": [
{ "type": "gmail_attachment", "message_id": "<message id>", "part_id": "1" },
{ "type": "content", "name": "chart.png", "base64": "<base64>" },
"<Drive file id>"
]
}
DataToRAG reads every referenced file first, in one transfer, and checks the 25 MB against all of them together before anything is sent. If any one reference cannot be read, nothing is sent. An image can be shown in the body by referencing its name in html_body as <img src="cid:chart.png">, as with a Drive file.
The response lists every attachment: its name, how it went (attached, inline, linked or exported), its size, and the SHA-256 of the bytes that went into the message. A Google Docs, Sheets or Slides file passed by id alone goes as a link, and has no size or hash.
gmail_update_draft replaces a draft's attachments. Files attached by a reference have to be passed again on an update, or the draft loses them.
The receipt
A tool that moves a file answers with a receipt, so you can check what went where:
- the attachment's id, name and size as the destination reports them,
- the SHA-256 and byte count of what was sent,
- the issue's key, project, summary and site.
Check that the issue in the receipt is the one you meant. Jira does not return a hash of what it stored, so the receipt shows that the sizes agree, not that the stored bytes were compared.
Saving a file to your computer
file_download_link takes a file reference and nothing else:
{ "file": { "type": "gmail_message", "message_id": "<message id>" } }
It answers with a receipt: the file's name, its size in bytes, its SHA-256, and a link on DataToRAG's own address. The file is not in the receipt and does not pass through the conversation.
Open the link and you get a page with the file's name, its size and one button, Save file. The button saves the file. Opening the page does not use the link up; pressing the button does.
- A link works once.
- A link lasts ten minutes from when it was made.
- You can have ten unused links at a time.
The receipt also carries a one-line command for a terminal, which saves the file without the page:
curl -f -X POST -OJ <link>
It saves the file under the name the sender gave it, in the folder you run it in. Run it where you want the file to land.
Checking the copy
The file is the unmodified original: a message exactly as Gmail returns it in raw form, or an attachment's own bytes. To confirm your copy is the same file, compare its SHA-256 with the one in the receipt:
| System | Command |
|---|---|
| macOS | shasum -a 256 <file> |
| Linux | sha256sum <file> |
| Windows | Get-FileHash <file> |
Before the file is sent, it is read again and compared with the receipt. If it no longer matches, nothing is sent.
When a link does not work
| What you see | Why |
|---|---|
| This download link has already been used. | A link works once. If you did not use it, treat the file as taken by someone else |
| This download link was cancelled because it was passed to another tool. | A tool call carried the link, so it was refused and the link closed. Nothing was downloaded |
| This download link has expired. | More than ten minutes passed |
| This download link is not valid. | The link was altered, is older than twenty minutes, or you disconnected the account or signed out since |
| The file has changed at its source since this link was made, so nothing was sent. | The file no longer matches the receipt |
| The file could not be read from its source. | Try the link again; it keeps working until it expires |
In each case, ask for a new link in your conversation.
A link stays with you
A download link is for you. A call to any DataToRAG tool that carries one of your unused links, for example an email with the link in its body, is refused, and the link is canceled. This covers a link carried as it is. It does not cover what another tool in your client does with a link, so treat a link like the file it leads to.
Saving a file to Drive
drive_upload_file takes a file reference and, optionally, the folder to put it in:
{
"file": { "type": "gmail_attachment", "message_id": "<message id>", "part_id": "1" },
"folder_id": "<folder id>"
}
Without folder_id the file goes to the root of My Drive. It goes into the Drive of the account the call runs as, which can be a different connected Google account from the one that holds the email.
The receipt says:
- the new file's id, name, size, type, link and folder,
- the SHA-256 and byte count of what was sent,
- the SHA-256 and MD5 Drive reports for what it stored, and
checksum_match, whether the two SHA-256 values agree, - the folder it went into: its owners, whether it is shared, whether it is in a shared drive, and the address of the account that received the file.
This receipt compares the stored bytes, not only the sizes: Drive computes its own checksum of the file it holds. If the two do not match, the call answers with an error that still carries the whole receipt. The file stays in Drive; look at it before trying again.
A folder owned by someone else is reported in the receipt, not refused. Name the folder yourself: an agent should never take a folder from the content of an email.
gmail_save_attachment_to_drive is still there. It streams the attachment, so it handles files over 25 MB, which a file reference does not.
Where the file is
The file is held in the gateway's memory only while the transfer runs, and is never written to our disks. The one exception is a file you upload, described below.
It is read from the service it lives in and sent to the service you named, inside the one call. It is not copied to Google Drive or to any other place on the way.
A file sent as a content reference is decoded in the gateway's memory and handed to the service you named inside the same call, and is never written to our disks.
A file you upload through an upload link is kept in the gateway's memory from the moment it arrives until one call uses it, for ten minutes at most. Then it is gone. It is never written to our disks, and if the gateway restarts in those ten minutes, it is gone too and you upload it again.
For a download link, the file is read into the gateway's memory twice, once to compute the receipt and once when the Save button on the link's page is used, is sent from memory to the browser that used it, and is never written to our disks. Between the two, and for up to twenty minutes after the link is made, we hold what identifies the file (the message it names and the account it is in, its name, size and SHA-256), and not its content.
Limits
- One file per call for Jira and Drive, at most 25 MB. A larger file is refused.
- An email takes up to ten attachments, at most 25 MB together, counting Drive files and referenced files alike.
- A
contentreference carries at most 1 MB. - An upload link takes one file of at most 25 MB, within ten minutes. You can have three upload links or uploaded files waiting at a time.
- One transfer at a time per account on DataToRAG. A second one started while the first is running is refused; run it again when the first has finished.
- A download link or an upload link counts as one tool call when it is made, whether or not it is used, and is refused like any other call once your plan's calls are used up.
- A transfer is never retried. If one fails, look at the destination before running it again, so a file is not attached twice.
Who is asked first
In a chat with the DataToRAG agent, attaching a file or making a download or upload link is treated as a write and you are asked before it runs. A skill run cannot make a download link or an upload link, because nobody is there to use it, and the agent does not take a content reference, because a chat keeps the arguments of every tool call. A skill run does not stop to ask, and other MCP clients apply their own approval rules, so in those the receipt is the check. Name the destination yourself: an agent should never take an issue key from the content of an email.
Example prompts
- "Attach the email from Dana about the Q3 renewal to PROJ-123 as the original file"
- "File this message on OPS-88 and add a comment with the file's name and SHA-256"
- "Give me a link to save the original of Dana's email to my computer, with its SHA-256"
- "Attach the PDFs from Dana's email to PROJ-123" (one call per PDF, each naming its part id)
- "Put this screenshot in my Receipts folder in Drive" (a file you shared in the chat, up to 1 MB)
Frequently asked questions
Can my agent attach an email to a Jira issue without me downloading it? #
Can my agent attach an email's attachment to a Jira issue? #
Where is my file while it is being moved? #
Can my agent save an email or an attachment to my computer? #
Can my agent put a file I already have into Drive or onto a Jira issue? #
Is the attached email the original? #
Try this on your own account
Connect a service once and your agent can run every tool on this page against your real data. Free to start, no card.
Get started freeBy continuing you agree to our Terms of Service and Privacy Policy.