FreeScout Email: SMTP, IMAP, SPF, DKIM & DMARC (2025)

Email is the lifeline of helpdesk software. Without proper configuration, FreeScout won't send or receive emails, and your support operation falls apart.

This guide covers every step: SMTP (sending), IMAP (receiving), and the authentication records (SPF/DKIM/DMARC) that keep your emails out of spam.

Email Basics: What You Need

FreeScout uses two separate email systems:

1. SMTP (Simple Mail Transfer Protocol): FreeScout uses this to send emails — your replies, notifications, auto-responders
2. IMAP (Internet Message Access Protocol): FreeScout uses this to fetch incoming emails from your mailbox

Both need to be configured for email to work. If one is wrong, half of your helpdesk breaks.

Where to Get Email Credentials

You have three options:

Option A: Gmail (simplest but most restrictive)

• Pros: Free, everyone knows it, easy setup
• Cons: Low send rate limits, Google blocks "less secure" apps, requires OAuth2 configuration
• Best for: Small teams (5–10 agents) with low ticket volume

Option B: Paid email service (SendGrid, Mailgun, Postmark)

• Pros: Reliable, high send rates, excellent deliverability, good support
• Cons: Costs $10–$30/month per domain
• Best for: Teams that care about email reaching the inbox (most businesses)

Option C: Your server's own mail server (Postfix, Exim)

• Pros: Free, no third-party dependency, full control
• Cons: Complex setup, reputation management headache, easy to mess up and land in spam
• Best for: Technical teams who want full control

Recommendation: Start with SendGrid ($10/month) or your domain registrar's email service. Avoid Gmail for business support — its rate limits are too restrictive.

Step 1: Configure SMTP (Sending Emails)

Open your FreeScout settings and navigate to Settings → Mail.

Fill in these fields (example using SendGrid):

Mail driver: SMTP
MAIL_HOST: smtp.sendgrid.net
MAIL_PORT: 587
MAIL_USERNAME: apikey
MAIL_PASSWORD: [your SendGrid API key]
MAIL_ENCRYPTION: tls
MAIL_FROM_ADDRESS: support@your-domain.com
MAIL_FROM_NAME: "Your Company Support"

Key points:

• MAIL_DRIVER: Use smtp (never use mail — it's deprecated)
• MAIL_HOST: Depends on your provider:
  • SendGrid: smtp.sendgrid.net
  • Mailgun: smtp.mailgun.org
  • Gmail: smtp.gmail.com
  • Your server: localhost
• MAIL_PORT: Use 587 (TLS) for most providers. Use 465 for Gmail. Never use 25 (unencrypted, deprecated)
• MAIL_ENCRYPTION: Use tls (Transport Layer Security). This encrypts the connection between FreeScout and the SMTP server
• MAIL_FROM_ADDRESS: This is the email address that appears in the "From" field of your replies. Use your actual support email, not a dummy address

Testing SMTP

Once configured, test it from FreeScout's settings:

Settings → Mail → "Send Test Email" button

If the test email arrives, SMTP is working. If it doesn't:

1. Check your SMTP credentials are 100% correct
2. Whitelist FreeScout's IP address in your mail provider (some providers require it)
3. Check your firewall isn't blocking port 587 or 465
4. If using Gmail, enable "Less Secure App Access" or configure OAuth2 (newer Gmail accounts require this)

Common error: Connection timeout → Your firewall is blocking the SMTP port. Ask your hosting provider to whitelist port 587/465.

Step 2: Configure IMAP (Receiving Emails)

Navigate to Settings → Mailboxes → Your Mailbox → IMAP Settings.

Fill in these fields (example using Gmail):

IMAP Server: imap.gmail.com
IMAP Port: 993
IMAP Username: your-email@gmail.com
IMAP Password: [your Gmail app password]
IMAP Encryption: SSL

Key points:

• IMAP Server: Depends on your provider. Most are obvious (imap.sendgrid.net, imap.mailgun.org, etc.)
• IMAP Port: Always 993 (SSL). Never use 143 (unencrypted)
• IMAP Encryption: Always SSL (Secure Sockets Layer). This encrypts the connection to the mailbox
• IMAP Username: Usually your full email address (support@your-domain.com)
• IMAP Password: For Gmail, you need an "App Password" (not your regular Gmail password):
  • Go to Google Account → Security → App Passwords
  • Generate one for "Mail" on your device
  • Copy that password here
• Validate SSL Certificate: Leave this ON unless you're using a self-signed certificate

Testing IMAP

FreeScout automatically tests IMAP when you save. If it fails:

1. Check your username/password are correct (typos are common)
2. For Gmail, ensure you're using an app password, not your regular password
3. Check the IMAP port is 993, not 143 or 143
4. If using Outlook, note that Outlook has special IMAP limits — see Outlook's docs

Common error: IMAP connection refused → Check port number (should be 993). If correct, your email provider might block IMAP on that port.

Step 3: Email Polling (How Often FreeScout Fetches Emails)

FreeScout checks your mailbox at regular intervals to fetch new emails.

Navigate to Settings → Mailboxes → Polling and set:

Polling interval: Every 5 minutes (for most teams)

Guidelines:

• Every 1 minute: Overkill. Wastes server resources for minimal benefit. Only use if you process 1000+ tickets/day
• Every 5 minutes: Standard. Customers see their replies within 5 minutes. Balanced resource usage
• Every 15 minutes: Acceptable. Longer delay, but saves server resources if you have many mailboxes
• Every 30+ minutes: Not recommended. Customers have to wait too long for responses to show up

After you set this, FreeScout runs a cron job every minute to check if it's time to poll. Your cron job (from the installation guide) must be running:

* * * * * /usr/bin/php /var/www/freescout/artisan schedule:run

If polling doesn't work:

1. Check your cron job is running: crontab -u www-data -l
2. Check FreeScout logs: tail -f /var/www/freescout/storage/logs/laravel.log

Step 4: Email Deliverability — The Critical Part

You've now configured sending (SMTP) and receiving (IMAP). But your emails still might land in spam. This step fixes that.

Email providers (Gmail, Outlook, Yahoo, etc.) use these records to verify your emails are legitimate:

SPF (Sender Policy Framework)

What it does: Tells email providers which IP addresses are allowed to send from your domain.

How to set it up:

1. Go to your domain registrar (GoDaddy, Namecheap, Route 53, Cloudflare, etc.)
2. Find DNS settings
3. Add a TXT record with these values:

Name: @ (or your domain)
Type: TXT
Value: v=spf1 ip4:YOUR_SERVER_IP ~all

Replace YOUR_SERVER_IP with your server's actual IP address.

Example:

v=spf1 ip4:203.0.113.42 ~all

Important: If you're using SendGrid, Mailgun, or another email service, use their SPF record instead. Ask them for it — it's usually something like:

v=spf1 include:sendgrid.net ~all

Verify it works:

dig your-domain.com TXT | grep spf

DKIM (DomainKeys Identified Mail)

What it does: Cryptographically signs outgoing emails to prove they really came from you.

How to set it up:

This is complex. Most teams use their email provider's DKIM setup:

If using SendGrid:

1. Go to SendGrid Dashboard → Settings → Sender Authentication
2. Click "Authenticate Your Domain"
3. SendGrid generates DKIM keys
4. Add those keys as DNS TXT records in your domain registrar
5. Verify

If using your own server (Postfix):

1. Generate a DKIM key pair (complex — usually done by your sysadmin)
2. Add the public key as a TXT record
3. Configure Postfix to sign outgoing emails with the private key

Recommendation: Use SendGrid or Mailgun for DKIM. It's free on their tier and handles all the complexity.

Verify it works:

dig default._domainkey.your-domain.com TXT

DMARC (Domain-based Message Authentication)

What it does: Tells email providers what to do with emails that fail SPF/DKIM.

How to set it up:

1. Go to your domain registrar DNS settings
2. Add a TXT record:

Name: _dmarc
Type: TXT
Value: v=DMARC1; p=quarantine; rua=mailto:admin@your-domain.com

Breaking this down:

• v=DMARC1 — DMARC version (always this)
• p=quarantine — policy. Options:
  • p=none — report failures but don't quarantine (testing mode)
  • p=quarantine — put failing emails in spam (recommended)
  • p=reject — reject failing emails (use only when you're confident)
• rua=mailto:admin@your-domain.com — email address to send weekly DMARC reports to

Example:

v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@your-domain.com

Verify it works:

dig _dmarc.your-domain.com TXT

Step 5: Reverse DNS (PTR Record)

What it does: Proves your server's IP address belongs to your domain.

Why it matters: Email providers check that your server's IP reverse-resolves to your domain. If it doesn't, your emails get flagged as suspicious.

How to set it up:

This is done at your hosting provider, not your domain registrar.

For example, if you're on DigitalOcean:

1. Go to Networking → Reserved IPs
2. Find your server's IP
3. Click "Edit Reverse DNS"
4. Set it to your domain: mail.your-domain.com

For Hetzner:

1. Go to Cloud Console → Servers
2. Click your server → Network
3. Find the reverse DNS field
4. Set it to your domain

For other providers, search "[your hosting provider] reverse DNS".

Verify it works:

dig -x YOUR_SERVER_IP +short

Should return your domain.

Checklist: Is Your Email Working?

Before you consider email fully configured, verify all of these:

• [ ] SMTP test email: Settings → Mail → Send Test Email works
• [ ] IMAP connection: Settings → Mailboxes → IMAP connection succeeds
• [ ] Incoming emails: Send a test email from outside FreeScout and see it appear in FreeScout
• [ ] Outgoing emails: Reply to a ticket in FreeScout and verify the recipient receives it
• [ ] SPF record: dig your-domain.com TXT | grep spf shows your SPF record
• [ ] DKIM record: dig default._domainkey.your-domain.com TXT shows DKIM public key
• [ ] DMARC record: dig _dmarc.your-domain.com TXT shows DMARC policy
• [ ] Reverse DNS: dig -x YOUR_SERVER_IP +short returns your domain
• [ ] Email not in spam: Send a test email to Gmail/Outlook and check it arrives in the inbox, not spam

Common Email Issues and Fixes

| Issue | Cause | Fix | |---|---|---| | "Emails not sending" | SMTP not configured or wrong credentials | Verify SMTP settings, run test email, check credentials | | Emails sending but slow | Polling interval too long | Reduce polling interval to 5 minutes | | IMAP not connecting | Wrong port or encryption | Use port 993 with SSL | | Emails go to spam | Missing SPF/DKIM/DMARC | Add all three DNS records | | Only receiving some emails | IMAP limit hit | Check email provider's IMAP connection limits | | Can't use Gmail IMAP | Google blocks "less secure" apps | Use app password instead of Gmail password |

Email Setup Time Budget

Email configuration typically takes:

• SMTP setup: 15 minutes
• IMAP setup: 15 minutes
• SPF/DKIM/DMARC setup: 30–60 minutes (depends on your registrar's interface)
• Reverse DNS setup: 10 minutes
• Testing and debugging: 30 minutes
• Total: 2–3 hours for a first-time setup

This is one of the most common places where DIY installations fail. SPF/DKIM/DMARC configuration requires navigating multiple DNS systems and waiting for DNS propagation (up to 48 hours).

FAQ: Email Edition

Q: Can I use multiple email addresses with FreeScout? A: Yes. FreeScout supports multiple mailboxes. Each mailbox has its own IMAP/SMTP configuration.

Q: What if I have multiple agents replying from different email addresses? A: Each agent can have their own "reply from" address. Configure it in their agent settings.

Q: How do I know if my emails are being rate-limited? A: Check FreeScout logs. If you see repeated errors like "451 Temporary Service Unavailable", you're hitting rate limits. Contact your email provider.

Q: Does FreeScout support OAuth2 for Gmail? A: Yes, via the Gmail OAuth2 module. It's more secure than app passwords but requires additional setup.

Q: What if my email provider doesn't provide SMTP/IMAP? A: They don't exist. Every email provider offers SMTP/IMAP. Check their support docs or contact their support.

Resources

• FreeScout Module Marketplace — official module marketplace
• Mail-Tester — test your email deliverability score
• MXToolbox — verify SPF, DKIM, and DMARC records
• Google Postmaster Tools — monitor Gmail delivery reputation
• EasyDMARC DKIM Generator — generate DKIM keys