Skip to main content

​
File Uploads & Attachments Guide

This comprehensive guide covers everything you need to know about working with files and attachments in Elementum, including size limits, upload methods, and best practices.
File Size Limit: Elementum supports file uploads up to 250MB per file across all upload methods. Note that email attachments have a lower limit of 25MB due to email service provider restrictions.

​
Understanding Files in Elementum

Elementum provides multiple ways to work with files, each designed for specific use cases. Understanding the differences will help you choose the right approach for your needs.

​
File Fields vs Attachments Component

File Fields

Purpose: Store a specific file in a designated field on a recordUse Cases:
  • Invoice file field on invoice records
  • Contract document field on contract records
  • Photo field on product records
Characteristics: Single file per field, structured storage

Attachments Component

Purpose: General-purpose file storage area for multiple filesUse Cases:
  • Supporting documents for a record
  • Multiple files uploaded by email
  • User-added supplementary files
Characteristics: Multiple files, flexible storage
Both File Fields and the Attachments component support files up to 250MB per file. They are complementary: use File Fields for structured, specific files and the Attachments component for general-purpose file storage.

​
Methods for Adding Files to Records

There are five primary ways to add files to records in Elementum. Each method serves different scenarios and integration needs.

​
1. Manual Upload in Layouts

How it works: Users directly upload files through the record interface. Best for:
  • User-initiated file uploads
  • Interactive workflows requiring document submission
  • Ad-hoc file additions to existing records
Implementation:
  • Add a File field to your layout for specific files
  • Add the Attachments component for general file storage
  • Configure field visibility and permissions as needed
Example Use Cases:
  • Employee uploading resume during onboarding
  • Customer submitting proof of purchase
  • Team member attaching project deliverables

​
2. Email Received Trigger

How it works: When automations create records from emails, any email attachments are automatically added to the new record. Best for:
  • Email-to-record workflows
  • Support ticket systems
  • Document collection via email
Configuration: 
Email Received Trigger → Create Record (Support Ticket)
  → Email attachments automatically saved to record
Key Points:
  • Attachments are saved to the Attachments component
  • Multiple attachments are supported
  • Use “Repeat for Each” action to process multiple attachments
  • Access attachments via trigger.attachments variable
Example Use Cases:
  • Support tickets with customer-submitted screenshots
  • Invoice processing from emailed PDFs
  • Document collection via dedicated email addresses

​
3. Send API Request Action

How it works: Download files from external APIs and save them as attachments using automation actions. Best for:
  • Integration with external systems
  • Automated file collection from APIs
  • Scheduled file downloads
Configuration: 
Automation Trigger → Send API Request (download file)
  → Save Attachment (store to record)
Key Points:
  • Set response type to FILE in Send API Request action
  • Use Save Attachment action to store the downloaded file
  • Supports various authentication methods (Bearer, OAuth, Basic Auth)
Example Use Cases:
  • Downloading reports from external reporting systems
  • Fetching documents from cloud storage APIs
  • Retrieving generated files from third-party services

​
4. External API Integration

How it works: Third-party systems add attachments via Elementum’s REST API endpoints. Best for:
  • System-to-system integrations
  • Custom applications adding files to Elementum
  • Automated workflows in external systems
API Endpoint: 
POST https://api.elementum.io/v1/elements/testelement/TTE-11/attachments
Authorization: Bearer <access_token>
Content-Type: multipart/form-data
Key Points:
  • Requires OAuth 2.0 authentication
  • Supports files up to 250MB
  • Returns attachment metadata upon success
  • Replace elements, testelement, and TTE-11 with your specific values
  • See API Documentation for details
Example Use Cases:
  • CRM system attaching contracts to customer records
  • Document management system syncing files
  • Custom applications uploading generated reports

​
5. File Fields in Records

How it works: Users or automations populate specific File field types on records. Best for:
  • Structured file storage with specific meaning
  • Required documents in workflows
  • Single file per field requirements
Configuration:
  • Create a File field in your Element definition
  • Add the field to your layout
  • Set field as required or optional
Key Points:
  • One file per field (unlike Attachments component)
  • Field-specific permissions and validations
  • Can be referenced in automations and reports
  • Ideal for structured data models
Example Use Cases:
  • “Invoice PDF” field on invoice records
  • “Employee Photo” field on employee records
  • “Contract Document” field on contract records

​
File Size Limits Summary

Understanding file size limits is critical for designing reliable workflows and setting user expectations.
OperationMaximum SizeNotes
File Field Upload250MBPer file
Attachments Component250MBPer file, multiple files supported
Email Attachments (Email Received)250MBPer file (system limit)
Email Attachments (Send Email)25MBTotal size of all attachments in one email
API Upload250MBPer file
File Reader Processing250MBPer file
Survey File Upload250MBPer file
The 25MB limit for sending email attachments is due to email service provider restrictions and is separate from the 250MB system-wide limit for file storage.

​
Working with Files in Automations

Automations provide powerful capabilities for processing and managing files automatically.

​
Accessing File Information

Email Received Trigger: 
trigger.attachments - Array of attachment objects
trigger.attachments[0].name - Filename
trigger.attachments[0].mediaType - File type
trigger.attachments[0].url - File URL
Attachment is Added Trigger: 
trigger.Name - Filename
trigger.Description - Attachment description
trigger.Media Type - File extension/format
trigger.URL - File URL
trigger.Size - File size

​
Processing Files

Extract text content from PDFs, DOC, DOCX, TXT, CSV, and Excel files.Example:
Attachment Added → Read File → Extract text content
  → Use in AI Classification or Update Record Fields
Use AI to intelligently analyze documents and extract structured data.Example:
Contract PDF → AI File Analysis
  → Extract: Parties, Dates, Terms, Obligations
  → Update Record Fields with structured data
Process multiple files simultaneously for batch operations.Example:
Multiple Reports Uploaded → Read Bulk File
  → Process all files → Aggregate data
Save files to specific records programmatically.Example:
Email with PDFs → Repeat for Each (attachment)
  → Save Attachment to Customer Record

​
Sending Files via Email

When sending emails with attachments in automations, you can attach files from multiple sources: Attachment Sources:
  • Record File Fields: Attach files from specific file fields on the trigger record
  • Attachments Block: Attach all files from the record’s attachments component
  • Workflow File Fields: Attach files from file fields available in the workflow context
Remember: Total email attachment size is limited to 25MB when sending emails. If you exceed this limit, the email will fail to send.

​
Best Practices

​
File Size Management

  • Display file size limits in your forms and interfaces
  • Include size limits in survey instructions
  • Provide clear error messages when limits are exceeded
  • Use File Readers for structured data extraction
  • Process large files asynchronously when possible
  • Consider file size when designing email workflows
  • Keep email attachments under 25MB total
  • For larger files, use File Fields or direct uploads
  • Consider providing download links instead of attaching large files

​
File Organization

  • Create specific File fields for important documents (e.g., “Contract”, “Invoice”)
  • Use meaningful field names that indicate file purpose
  • Set File fields as required when documents are mandatory
  • Use the Attachments component for supplementary files
  • Allow users to add multiple supporting documents
  • Leverage attachments for email-based file collection
  • Encourage meaningful file names from users
  • Use automation to rename files based on record data
  • Include dates or identifiers in file names for easier searching

​
Security & Compliance

  • Use “Attachment is Added” trigger to validate file types
  • Block or flag unexpected file types
  • Implement virus scanning for sensitive environments
  • Configure field-level permissions for sensitive files
  • Use record-level permissions to control file access
  • Audit file access through activity logs
  • Never commit files with credentials or secrets (.env, credentials.json)
  • Use AI File Analysis to scan for sensitive information
  • Implement approval workflows for sensitive document types

​
Troubleshooting Common Issues

​
File Upload Failures

Symptoms: File upload fails or times out Solutions:
  • Verify file is under 250MB size limit
  • Check internet connection and upload speed
  • Try uploading a smaller file to isolate the issue
  • Review browser compatibility (test different browsers)

​
Email Attachment Errors

Symptoms: “Email failed to send” errors in automation logs Solutions:
  • Verify total attachment size is under 25MB
  • Check that all referenced file fields contain valid files
  • Ensure file URLs are accessible
  • Review email service provider status

​
File Processing Issues

Symptoms: File Readers fail to extract data correctly Solutions:
  • Verify file format is supported (PDF, DOC, DOCX, TXT, CSV, Excel)
  • Check file size is under 250MB
  • Test with a simpler file to rule out corruption
  • Review File Reader configuration and field mappings

​
API Upload Problems

Symptoms: API returns errors when uploading files Solutions:
  • Verify OAuth token is valid and not expired
  • Check Content-Type header is set to multipart/form-data
  • Ensure file size is under 250MB
  • Review API error message for specific issues

Automation Actions

Learn about file-related automation actions like Read File, AI File Analysis, and Save Attachment

Automation Triggers

Understand the Email Received and Attachment is Added triggers for file workflows

File Readers

Explore File Reader types and how to extract data from documents

API Reference

Review API endpoints for programmatic file uploads and management

Layouts & Fields

Configure File fields and Attachments component in your record layouts

Survey System

Use Upload File question type in surveys for collecting files from respondents

​
Summary

  • File Size Limit: 250MB per file (25MB for email sending)
  • Five Upload Methods: Manual, Email, API Action, External API, File Fields
  • Two Storage Types: File Fields (structured) and Attachments Component (flexible)
  • Automation Support: Read, analyze, and process files in workflows
  • Best Practice: Choose the right method for your use case and set clear expectations
Start with manual uploads and the Attachments component for simple use cases, then expand to automated file processing as your workflows mature.