@devries-cameron20 / composio-1 / commits / e838d50a2
Fork 0

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)

## Summary of Changes - Updated `docs/content/docs/tools-direct/executing-tools.mdx` File Upload section: added explanatory sentence about SDK auto-conversion and a URL-based Gmail attachment example alongside the existing local file path example - Added FAQ entry to `docs/content/toolkits/faq/gmail.md` explaining how to send emails with attachments using a URL or file path string directly, with generic phrasing about applicability to other file-uploadable tools ## Reasoning - Users see the `attachment` schema as `{ s3key, name, mimetype }` and incorrectly put public URLs in the `s3key` field, which fails - The SDK's auto-upload feature (enabled by default) accepts URLs and file paths directly, but this wasn't documented with a concrete example - The Gmail FAQ had no mention of how to handle attachments at all Co-authored-by: decimal-pr-bot[bot] <264021074+decimal-pr-bot[bot]@users.noreply.github.com>

decimal-pr-bot[bot] committed May 4, 2026 at 23:13 UTC e838d50a28d5867536667a3ac3647ea4126b7456
2 files changed +55 -1
docs/content/docs/tools-direct/executing-tools.mdx
+36 -1
@@ -316,7 +316,7 @@ Automatic file handling is **off by default**. Enable it with `dangerouslyAllowA
316
317 ### File Upload
318
319 -Pass local file paths, URLs, or File objects to tools that accept files:
319 +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.
320
321 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
322 <Tab value="Python">
@@ -359,6 +359,41 @@ console.log(result.data); // Contains Google Drive file details
359 </Tab>
360 </Tabs>
361
362 +This also works with public URLs. For example, to send a Gmail email with an attachment from a URL:
363 +
364 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
365 + <Tab value="Python">
366 +```python
367 +result = composio.tools.execute(
368 + slug="GMAIL_SEND_EMAIL",
369 + user_id="user-1235***",
370 + arguments={
371 + "recipient_email": "recipient@example.com",
372 + "subject": "Report attached",
373 + "body": "Please find the report attached.",
374 + "attachment": "https://example.com/report.pdf",
375 + },
376 +)
377 +```
378 + </Tab>
379 + <Tab value="TypeScript">
380 +```typescript
381 +import { Composio } from '@composio/core';
382 +const composio = new Composio({ apiKey: 'your_api_key' });
383 +// ---cut---
384 +const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {
385 + userId: 'user-1235***',
386 + arguments: {
387 + recipient_email: 'recipient@example.com',
388 + subject: 'Report attached',
389 + body: 'Please find the report attached.',
390 + attachment: 'https://example.com/report.pdf',
391 + },
392 +});
393 +```
394 + </Tab>
395 +</Tabs>
396 +
397 ### File Download
398
399 When tools return files, Composio downloads them to the local directory and provides the file path in the response:
docs/content/toolkits/faq/gmail.md
+19
@@ -32,4 +32,23 @@ Gmail triggers poll roughly every minute by default. If you need lower latency,
32
33 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.
34
35 +## How do I send an email with an attachment?
36 +
37 +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.
38 +
39 +```python
40 +result = composio.tools.execute(
41 + slug="GMAIL_SEND_EMAIL",
42 + user_id="user-123",
43 + arguments={
44 + "recipient_email": "recipient@example.com",
45 + "subject": "Report attached",
46 + "body": "See attached.",
47 + "attachment": "https://example.com/report.pdf",
48 + },
49 +)
50 +```
51 +
52 +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.
53 +
54 ---