Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: document that SDK auto-upload accepts URLs for file attachment parameters (#3244)

decimal-pr-bot[bot]e838d50a28d5
diff --git a/docs/content/docs/tools-direct/executing-tools.mdx b/docs/content/docs/tools-direct/executing-tools.mdx
index 5ff605929..7b8388064 100644
--- a/docs/content/docs/tools-direct/executing-tools.mdx
+++ b/docs/content/docs/tools-direct/executing-tools.mdx
@@ -316,7 +316,7 @@ Automatic file handling is **off by default**. Enable it with `dangerouslyAllowA
### File Upload
-Pass local file paths, URLs, or File objects to tools that accept files:
+Pass local file paths, URLs, or File objects to tools that accept files. The SDK uploads the file to Composio's storage and converts it to the format the tool expects — you don't need to construct the file metadata object (`s3key`, `name`, `mimetype`) yourself.
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
@@ -359,6 +359,41 @@ console.log(result.data); // Contains Google Drive file details
</Tab>
</Tabs>
+This also works with public URLs. For example, to send a Gmail email with an attachment from a URL:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+result = composio.tools.execute(
+ slug="GMAIL_SEND_EMAIL",
+ user_id="user-1235***",
+ arguments={
+ "recipient_email": "[email protected]",
+ "subject": "Report attached",
+ "body": "Please find the report attached.",
+ "attachment": "https://example.com/report.pdf",
+ },
+)
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {
+ userId: 'user-1235***',
+ arguments: {
+ recipient_email: '[email protected]',
+ subject: 'Report attached',
+ body: 'Please find the report attached.',
+ attachment: 'https://example.com/report.pdf',
+ },
+});
+```
+ </Tab>
+</Tabs>
+
### File Download
When tools return files, Composio downloads them to the local directory and provides the file path in the response:
diff --git a/docs/content/toolkits/faq/gmail.md b/docs/content/toolkits/faq/gmail.md
index d336bedf1..3a06cc60e 100644
--- a/docs/content/toolkits/faq/gmail.md
+++ b/docs/content/toolkits/faq/gmail.md
@@ -32,4 +32,23 @@ Gmail triggers poll roughly every minute by default. If you need lower latency,
Google enforces per-minute and daily request quotas. If you're using Composio's default OAuth app, you share that quota with other users, which can cause limits to be hit faster. Use your own OAuth app credentials to get a dedicated quota, and add exponential backoff and retries to handle transient rate limits.
+## How do I send an email with an attachment?
+
+When using the Composio SDK, pass a local file path or a public URL directly as a string to the `attachment` field. The SDK's auto-upload feature (enabled by default) handles uploading the file and converting it to the required format. You do not need to construct the `{ s3key, name, mimetype }` object manually.
+
+```python
+result = composio.tools.execute(
+ slug="GMAIL_SEND_EMAIL",
+ user_id="user-123",
+ arguments={
+ "recipient_email": "[email protected]",
+ "subject": "Report attached",
+ "body": "See attached.",
+ "attachment": "https://example.com/report.pdf",
+ },
+)
+```
+
+This approach works for any tool whose parameters accept file uploads. See [Automatic File Handling](/docs/tools-direct/executing-tools#automatic-file-handling) for more details.
+
---