How to Resolve the Issue of Fetching Large Emails in FreeScout

4 min read

FreeScout is a powerful tool for managing customer communications, but it encounters issues with emails containing large attachments due to limitations in the webklex/php-imap library. Specifically, emails exceeding 18MB can fail to fetch because handling such files requires significant memory allocation. For instance, fetching a single email with an 18MB attachment may require at least 400MB of PHP memory.

This article explains the issue and provides step-by-step guidance to resolve it. Additionally, it covers email size limits for common platforms like Google Workspace and Microsoft 365 to help you set appropriate limits.

Step 1: Understand the Issue and Verify the Symptoms

Locate FreeScout's Error Logs
FreeScout’s error logs can be found in the following directory on your server:
```
/storage/logs/
```
The main log file is typically named laravel.log. Use a text editor or log viewer to access the file.

What the Error Looks Like

On the FreeScout UI
If an error occurs due to large email attachments, the UI will display a generic message like:
```
Whoops, looks like something went wrong — check logs in /storage/logs
```

In the Logs (laravel.log)
Look for specific entries indicating memory exhaustion. Here’s an example of what the log might contain:

[2024-12-28 15:32:16] production.ERROR: Allowed memory size of 763363328 bytes exhausted (tried to allocate 8837520 bytes) {"userId":1,"email":"[email protected]","exception":"[object] (Symfony\\Component\\Debug\\Exception\\FatalErrorException(code: 1): Allowed memory size of 763363328 bytes exhausted (tried to allocate 8837520 bytes) at /home/projects/webapps/app-helpdesk/public/vendor/laravel/framework/src/Illuminate/Cache/FileStore.php:187)

Key Signs to Identify
- "Allowed memory size of X bytes exhausted": Indicates that the PHP memory limit has been reached.
- Path to the problematic file: Example: /vendor/laravel/framework/src/Illuminate/Cache/FileStore.php:187.
- Specific allocation attempts: Example: tried to allocate 8837520 bytes.
Confirm the Root Cause
If the logs indicate memory exhaustion while processing large emails or attachments, it confirms the issue is related to insufficient memory allocation for handling large files. Move on to the subsequent steps to address the problem.

Step 2: Email Size Limits in Popular Platforms

To design an effective solution, consider the email size limits enforced by common email providers:

Google Workspace (Gmail):
- Maximum email size (including attachments): 25MB
- Emails exceeding this limit are rejected.
Microsoft 365 (Outlook):
- Maximum email size (including attachments): 35MB (default), adjustable up to 150MB for administrators.
- Large emails may still face practical issues like client limitations or slow delivery.

If your FreeScout installation must handle emails larger than these limits, consider alternative methods for attachment delivery, such as cloud storage links.

Step 3: Assess and Adjust PHP Memory Limit

Locate the php.ini file for your FreeScout installation. Typically, this is found in:
- /etc/php/7.x/cli/ (Command-line interface) or
- /etc/php/7.x/apache2/ (Apache server).
Check the current memory limit by opening the php.ini file:
```
sudo nano /etc/php/7.x/apache2/php.ini
```
Look for the memory_limit directive and increase it:
```
memory_limit = 2048M
```
Save and exit the file, then restart your web server to apply the changes:
```
sudo service apache2 restart
```

Step 4: Set a Hard Limit on Email Size in Your Email Server

To prevent FreeScout from attempting to process excessively large emails, set a size limit on your email server.

For Postfix (Linux-based mail servers): Edit the main.cf file and add:
```
message_size_limit = 20000000
```
This limits emails to 20MB. Restart Postfix to apply:
```
sudo systemctl restart postfix
```
For Microsoft 365 (Exchange Online):
- Log into the Exchange Admin Centre.
- Navigate to Mail Flow > Rules.
- Create a new rule to reject messages exceeding a specific size (e.g., 20MB).
For Google Workspace (Gmail): Gmail automatically enforces the 25MB limit. No additional configuration is required.

Step 6: Encourage Smarter Attachment Practices

To minimise issues with large attachments:

Request customers to use cloud storage links (Google Drive, OneDrive, Dropbox) for files exceeding platform limits.
Suggest splitting large files into smaller parts before sending them via email.

Further notes...

Emails with large attachments can disrupt FreeScout's functionality due to memory constraints. By increasing the PHP memory limit and configuring a hard cap on email sizes at the server level, you can mitigate this issue.

Awareness of email size limits for platforms like Google Workspace and Microsoft 365 helps set realistic boundaries. Finally, encourage smarter practices such as using cloud storage links for oversized files to ensure smooth operations in FreeScout.

Reference links

Github Issue (Apr 2024)