Monica CRM is a privacy-focused personal relationship manager. Successfully configuring outbound email is essential for notifications and automations. One of the most common issues for new users is encountering errors related to SSL or STARTTLS when setting up SMTP delivery. This guide provides step-by-step instructions, optimal configuration examples using environment variables, and explanations to help ensure your Monica CRM deployment sends emails reliably.

Common Problem: SSL Certificate Verification Error#

When Monica CRM is unable to verify the SSL certificate of your mail server, you might encounter an error such as:

In SocketStream.php line 171:

  Unable to connect with STARTTLS: stream_socket_enable_crypto(): SSL operation failed with code 1. OpenSSL Error
  messages:
  error:0A000086:SSL routines::certificate verify failed

This block indicates that SSL peer verification failed—often due to self-signed certificates or internal/private mail servers.

Optimal Email Configuration for Monica CRM#

To address these errors, use the following environment variable settings. These should be placed in your shell before launching Monica CRM, or specified in your deployment scripts. Note the use of export, which is standard for POSIX shells and compatible with most container setups:

export MAIL_DRIVER="smtp"
export MAIL_ENCRYPTION="null"
export MAIL_FROM_ADDRESS="[email protected]"
export MAIL_HOST="server"
export MAIL_PORT="25"
export MAIL_VERIFY_PEER="false"

What Each Setting Means#

  • MAIL_DRIVER="smtp" Instructs Monica to use SMTP for sending mail.
  • MAIL_ENCRYPTION="null" Disables encryption. Use this setting if your mail server does not support STARTTLS or is behind a firewall/trusted network. Avoid disabling encryption for public traffic—use it only on trusted/internal connections.
  • MAIL_FROM_ADDRESS Sets the address that appears in the “From” field of emails Monica sends.
  • MAIL_HOST Specifies your SMTP server’s address or hostname.
  • MAIL_PORT="25" Uses the standard SMTP port.
  • MAIL_VERIFY_PEER="false" This setting is crucial. It disables verification of the SSL certificate provided by your SMTP server, necessary when dealing with self-signed certs or internal servers. For security, only use this in trusted or development environments. In production, leaving this set to "true" is more secure.

Why MAIL_VERIFY_PEER is Important#

Setting MAIL_VERIFY_PEER="false" tells Monica CRM not to check whether the mail server’s SSL certificate is trusted. This resolves errors with self-signed or untrusted certificates, a common scenario in corporate or local test environments. If you omit or misconfigure this setting, Monica CRM may refuse to send emails due to failed certificate checks.

Tip: For internet-facing production systems, use "true" and ensure your SMTP server presents a valid, trusted certificate.

Applying and Testing Your Monica CRM Email Configuration#

After setting your environment variables as above, follow these steps:

1. Cache Your Updated Configuration#

Run the following command to cache your new configuration:

php artisan config:cache

Expected output:

INFO  Configuration cached successfully.

2. Send a Test Email#

Verify that your emails are being sent with the Monica command-line tool:

php artisan monica:test-email

You’ll be prompted to enter an email address:

What email address should I send the test email to?:
> [email protected]

If everything is configured correctly, you’ll see:

Preparing and sending email to "[email protected]"
Email sent!

Example Workflow#

Here’s the full process in context:

# Set environment variables for Monica CRM
export MAIL_DRIVER="smtp"
export MAIL_ENCRYPTION="null"
export MAIL_FROM_ADDRESS="[email protected]"
export MAIL_HOST="server"
export MAIL_PORT="25"
export MAIL_VERIFY_PEER="false"

# Apply the new configuration
php artisan config:cache

# Verify by sending a test email
php artisan monica:test-email

Best Practices and Security Considerations#

  • Always use encryption (MAIL_ENCRYPTION="tls" or "ssl") and set MAIL_VERIFY_PEER="true" for publicly accessible environments.
  • Only disable peer verification for internal testing or in environments where you control both the Monica CRM instance and the email server, and trust the network.
  • After any change to your environment variables, always run php artisan config:cache before testing.

Conclusion#

Configuring Monica CRM with the right SMTP settings maximizes email reliability and helps you avoid frustrating SSL and certificate errors. The most critical step for resolving certificate verification problems is setting MAIL_VERIFY_PEER="false"—but remember, for public or production use, you should strive for proper certificate validation and encryption.