Attachment processing

EmailConnect provides flexible options for handling email attachments, from simple inline delivery to cloud storage integration.

Processing options

When configuring an alias, you can choose how attachments are processed:

Inline (default)

Attachments are Base64-encoded and included directly in the webhook payload.

How it works:

  1. Email arrives with attachment
  2. Attachment is converted to Base64
  3. Encoded content is included in the webhook JSON
  4. Your application decodes and processes the file

Payload example:

{
  "attachments": [
    {
      "filename": "invoice.pdf",
      "contentType": "application/pdf",
      "size": 125840,
      "content": "JVBERi0xLjQKJeHp69MKMSAwIG9iago8PC9UeX...",
      "virusScan": { "status": "clean" }
    }
  ]
}

Best for:

  • Small to medium attachments (under 10MB)
  • Simple webhook endpoints
  • Quick prototypes and MVPs
  • When you need immediate file access

Considerations:

  • Increases webhook payload size
  • May hit size limits on some webhook receivers
  • Higher memory usage during processing

Managed S3 storage

Attachments are uploaded to EmailConnect's managed S3 storage, and your webhook receives secure URLs.

How it works:

  1. Email arrives with attachment
  2. Attachment is uploaded to managed S3 storage
  3. Webhook receives a pre-signed URL
  4. Your application downloads the file when needed

Payload example:

{
  "attachments": [
    {
      "filename": "invoice.pdf",
      "contentType": "application/pdf",
      "size": 125840,
      "url": "https://static.emailconnect.eu/attachments/...",
      "status": "completed",
      "virusScan": { "status": "clean" }
    }
  ]
}

Best for:

  • Large attachments (over 10MB)
  • High-volume processing
  • When webhook endpoints have size limits
  • Deferred processing workflows

Considerations:

  • Requires additional HTTP request to fetch files
  • URLs expire after a set period
  • Slight processing delay for upload

Custom S3 storage

Configure your own S3-compatible bucket for full control over attachment storage.

How it works:

  1. Email arrives with attachment
  2. Attachment is uploaded directly to your bucket
  3. Webhook receives the file location in your bucket
  4. You control retention, access, and lifecycle

Required configuration:

  • Bucket name
  • Region
  • Access key ID
  • Secret access key
  • Optional: custom endpoint (for S3-compatible services)

Best for:

  • Corporate compliance requirements
  • Long-term file retention
  • Custom access policies
  • High-volume cost optimization

Compatible services:

  • AWS S3
  • MinIO
  • Backblaze B2
  • DigitalOcean Spaces
  • Cloudflare R2

Attachment metadata

Regardless of processing mode, each attachment includes:

Field Description
filename Original file name
contentType MIME type (e.g., application/pdf)
size File size in bytes
content or url Base64 content or download URL

Size limits

Plan Max attachment size Max total per email
Free Not available Not available
Maker 10 MB (configurable) 10 MB
Business 10 MB (configurable) 10 MB
Platform 10 MB (configurable) 10 MB

Emails exceeding size limits are rejected with an appropriate error message to the sender.

Security considerations

Virus scanning

Available on Business+ plans. Every attachment is scanned for malware before delivery. Clean files are delivered normally with scan metadata; infected files are rejected and excluded from the payload.

See Virus scanning for full details on how scanning works, definition updates, and testing with the EICAR test file.

File type filtering

Use alias rules to block specific file types:

  • Executable files (.exe, .bat, .cmd)
  • Scripts (.js, .vbs, .ps1)
  • Compressed archives (optional)

Content validation

While we scan for malware, always validate and sanitize attachments in your application before processing.

Processing attachments in your application

Decoding Base64 (inline mode)

Node.js

const buffer = Buffer.from(attachment.content, 'base64');
fs.writeFileSync(attachment.filename, buffer);

Python

import base64

content = base64.b64decode(attachment['content'])
with open(attachment['filename'], 'wb') as f:
    f.write(content)

Downloading from URL (S3 mode)

Node.js

const response = await fetch(attachment.url);
const buffer = await response.arrayBuffer();

Python

import requests

response = requests.get(attachment['url'])
content = response.content

Common use cases

Document processing

  • Store in managed S3 for batch OCR processing
  • Use inline for real-time document analysis
  • Filter to accept only PDF and Office formats

Image handling

  • Inline for thumbnail generation
  • Managed S3 storage for high-resolution archives
  • Custom S3 for CDN integration

Compliance archival

  • Custom S3 for regulated data storage
  • Configure retention policies in your bucket
  • Maintain audit trails with your infrastructure

Related topics