File Handling Example

Learn how to handle file uploads and attachments with Composio tools

This example demonstrates how to use Composio tools that support file handling, such as sending emails with attachments using Gmail.

Overview

In this example, you’ll learn how to:

• Pass file paths to tools that support attachments
• Send emails with file attachments using Gmail
• Work with local file paths in tool arguments

Prerequisites

1. Install dependencies

   npm install @composio/core dotenv
   
2. Set up environment variables

   Create a .env file with your API key:

   COMPOSIO_API_KEY=your_composio_api_key
   
3. Connect your Gmail account

   Use Composio CLI to authenticate with Gmail:

   composio add gmail
   

   This will open a browser window for OAuth authentication.

Complete Example

import { Composio } from '@composio/core';
import 'dotenv/config';
import path from 'path';

/**
 * Initialize Composio
 */
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

/**
 * Main function to run the example
 */
async function main() {
  try {
    console.log('🚀 Starting File-handling Example...');

    // Get available tools
    const tools = await composio.tools.get('default', 'GMAIL_SEND_EMAIL');

    console.log(`✅ Found ${tools.length} tools`);

    const filePath = path.join(__dirname, '..', 'pepe-silvia.png');
    console.log(`Sending file from ${filePath}`);

    const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {
      userId: 'default',
      arguments: {
        attachment: filePath,
        recipient_email: '[e-mail]',
        user_id: 'me',
        body: 'Hello, this is a test email with a file attachment.',
        subject: 'Test Email with Attachment',
      },
    });

    console.log(result);
  } catch (error) {
    console.error('❌ Error running example:', error);
  }
}

// Run the example
main().catch(console.error);

How It Works

1. Initialize Composio

   Create a Composio instance with your API key.

2. Fetch Gmail Tool

   Get the GMAIL_SEND_EMAIL tool which supports file attachments.

3. Prepare File Path

   Use Node’s path module to construct the absolute path to your file. Composio handles reading and encoding the file.

4. Execute with Attachment

   Pass the file path in the attachment parameter. Composio automatically:

   • Reads the file from the filesystem
   • Encodes it appropriately (base64 for email)
   • Includes it in the API request

Tool Parameters

attachment · string

Absolute or relative file path to the attachment

recipient_email · string · required

Email address of the recipient

subject · string · required

Email subject line

body · string · required

Email body content (plain text or HTML)

user_id · string

Gmail user ID (use ‘me’ for authenticated user)

Expected Output

🚀 Starting File-handling Example...
✅ Found 1 tools
Sending file from /path/to/project/pepe-silvia.png
{
  successful: true,
  data: {
    id: '18d1234567890abcd',
    threadId: '18d1234567890abcd',
    labelIds: ['SENT']
  },
  error: null
}

Supported File Types

Composio automatically handles various file types based on the tool:

Email Attachments (Gmail, Outlook)

• Images: .png, .jpg, .jpeg, .gif, .bmp
• Documents: .pdf, .doc, .docx, .txt
• Spreadsheets: .xls, .xlsx, .csv
• Presentations: .ppt, .pptx
• Archives: .zip, .tar, .gz

File Upload Tools (Drive, Dropbox)

All file types are supported. The tool will preserve the original file format and metadata.

Image Processing Tools

Specific image formats depending on the tool (typically .png, .jpg, .jpeg, .webp)

Multiple Attachments

Some tools support multiple attachments. Check the tool schema:

const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {
  userId: 'default',
  arguments: {
    attachments: [
      path.join(__dirname, 'file1.pdf'),
      path.join(__dirname, 'file2.png'),
    ],
    recipient_email: '[e-mail]',
    subject: 'Multiple Attachments',
    body: 'Email with multiple files',
  },
});

URL-Based File Handling

You can also pass URLs for some tools:

const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {
  userId: 'default',
  arguments: {
    attachment: 'https://example.com/document.pdf',
    recipient_email: '[e-mail]',
    subject: 'Document from URL',
    body: 'Attached document from URL',
  },
});

Error Handling

File Not Found

try {
  const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {
    userId: 'default',
    arguments: {
      attachment: '/nonexistent/file.pdf',
      // ... other params
    },
  });
} catch (error) {
  console.error('File not found:', error.message);
}

Best Practices

Use Absolute Paths: Always use absolute paths or resolve relative paths using path.join() or path.resolve()

Check File Size: Be aware of size limits for different services (e.g., Gmail has a 25MB limit)

Validate File Exists: Check if the file exists before attempting to send it

Handle Errors: Always wrap file operations in try-catch blocks to handle missing files or permission errors

Next Steps

Custom Tools

Create custom tools with file handling

OpenAI Example

Combine file handling with AI agents