Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/composiohq/composio/llms.txt

Use this file to discover all available pages before exploring further.

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: 'musthaq@composio.dev',
        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:
  • Images: .png, .jpg, .jpeg, .gif, .bmp
  • Documents: .pdf, .doc, .docx, .txt
  • Spreadsheets: .xls, .xlsx, .csv
  • Presentations: .ppt, .pptx
  • Archives: .zip, .tar, .gz
All file types are supported. The tool will preserve the original file format and metadata.
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: 'user@example.com',
    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: 'user@example.com',
    subject: 'Document from URL',
    body: 'Attached document from URL',
  },
});

​
Error Handling

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

Build docs developers (and LLMs) love

Get started for freeTalk to us