Recipient name missing in "To" field when sending emails (raw email headers)

[jhack_jos]

Thank you in advance for your consideration.

Issue:
We’re experiencing an issue when sending emails via SMTP (we’re using Gmail as the mail server, with the Google Integration Extension). Here’s an example of the email headers:

From: Company Name <noreply@company.com>
To: customer@example.com

The From field is correctly formatted with the company name, but the To field only shows the email address of the recipient, without their full name (e.g., it should be “Mario Rossi <customer@example.com>”).
The full name of the contact is present in EspoCRM, but it’s not included in the message header.

This becomes a problem because we use Gmail’s sent folder for archiving and searching, and Gmail doesn’t allow us to search by the contact’s name unless it’s explicitly included in the To field. Not all our team is using EspoCRM, so we need to keep being able to find customers by name also in the Gmail app.

For clarity I also send the full anonymized raw email headers mentioned above below:

Return-Path: <noreply@company.com>
Received: from mailhost (mail.provider.com. [XXX.XXX.XXX.XXX])
by smtp.example.com with ESMTPSA id XXXXXXXXXXXXXXXX.XXX.2025.04.21.10.19.04
for <customer@example.com>
(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
Mon, 21 Apr 2025 10:19:04 -0700 (PDT)
Date: Mon, 21 Apr 2025 17:19:03 +0000
From: Company Name <noreply@company.com>
To: customer@example.com
Subject: TEST
MIME-Version: 1.0
Content-Type: multipart/alternative; boundary="=_random_boundary_string"
Message-ID: <Entity/xxxxxxxxxxxxxxxx/1234567890/0001@crm>

--=_random_boundary_string
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

TEST
--=_random_boundary_string
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: quoted-printable

<p>TEST</p>
--=_random_boundary_string--

Request:
Would it be possible to have EspoCRM include the contact’s name in the To field if it’s available in the contact record?
For example:

To: Mario Rossi <customer@example.com>
This small change would greatly improve email traceability and usability in Gmail and other email servers.

Thanks in advance!
Jacopo

[yuri]

Hi Jacopo,

We will look into this problem. But it can take some time. Unlikely in the next release. There's the problem that one might not will to expose the name a contact is given in the CRM with the recipient.

[yuri]

IFAIK it's a normal practice not to include the contact name in the To header.

> This small change..

Unfortunately, it's not not a small change. Email Address, Leads, Contact, Account are all different entities. Now we deal only with addresses. Adding a person/company record may require a lot of effort.

[jhack_jos]

Thank you for your prompt reply, Yuri — I really appreciate it.

As I understand it, this modification might also slightly affect spam filter heuristics in a positive way.

---

I hope it’s not off-topic to ask this here.

We have a strong need for this feature in our team, so I’m exploring ways to make it temporarily work in our EspoCRM instance. I’m a beginner with the EspoCRM source code, and I’m likely making wrong assumptions or touching things I shouldn’t — but I hope you can help point me in the right direction.

I noticed that in the Sender::addAddresses() method, if I change:

$message->addTo(trim($address));

to:

$message->addTo(trim($address), "name");

...then the raw email headers correctly show "name <email@example.com>".

My current challenge is: how can I access the correct name for each email address within the scope of this method, as you mentioned?

Initially, I thought the addressNameMap field in the database could help, but it doesn’t seem to be populated for outbound messages.

However, when viewing a sent email in the Espo UI, the To field always shows the name next to the email address, even when the parent attribute is empty. I suppose that means the data should exist somewhere. How is this accomplished in the frontend? If I could reproduce that same logic in addAddresses(), I think I could implement a workable temporary solution.

Any guidance would be very appreciated. Thank you in advance!

[yuri]

In v9.1 there was refactoring done and we switched the library. I recommend starting customizing after it's released.

[jhack_jos]

Thank you for the suggestion, Yuri. I'm looking forward to the release of version 9.1 and the improvements you've mentioned.

In the meantime, I kept digging into the issue and found a potential workaround. It turns out that the data can be accessed via:

$email->get("nameHash")->{$address};

Below is the modified Sender::addAddresses() method, which I’ve tested successfully in my EspoCRM instance. It adds support for including recipient names (e.g., Name <email>) in the outgoing email headers using the nameHash field.

To make this fully user-friendly, the next step would be to introduce a toggle in the SMTP settings UI to enable or disable this feature.
I am also aware that the cast to array may not be ideal, and depending on your policy you may want to stick on working on stdClass objects.

private function addAddresses(Email $email, Message $message): void
{
    $value = $email->get('to');
    $nameHash = (array) $email->get('nameHash') ?? [];

    if ($value) {
        foreach (explode(';', $value) as $address) {
            $address = trim($address);
            $name = isset($nameHash[$address]) ? trim($nameHash[$address]) : null;
            $message->addTo($address, $name);
        }
    }

    $value = $email->get('cc');
    if ($value) {
        foreach (explode(';', $value) as $address) {
            $address = trim($address);
            $name = isset($nameHash[$address]) ? trim($nameHash[$address]) : null;
            $message->addCC($address, $name);
        }
    }

    $value = $email->get('bcc');
    if ($value) {
        foreach (explode(';', $value) as $address) {
            $address = trim($address);
            $name = isset($nameHash[$address]) ? trim($nameHash[$address]) : null;
            $message->addBCC($address, $name);
        }
    }

    $value = $email->get('replyTo');
    if ($value) {
        foreach (explode(';', $value) as $address) {
            $address = trim($address);
            $name = isset($nameHash[$address]) ? trim($nameHash[$address]) : null;
            $message->addReplyTo($address, $name);
        }
    }
}

Let me know if I may be of help bringing this feature to light in the official EspoCRM distribution.
Jacopo

[yuri]

The name hash data is not always there as it's an externally loaded field. In some cases it won't be loaded. It's a more complex to solve problem than it may seem.

[jhack_jos]

Thank you for your feedback Yuri, that's very helpful in getting a grasp of the problem.
I checked what you meant by "externally loaded field" looking at the source, and I can see how the loadNameHash() method is quite complex.
As you recommended we'll be waiting for 9.1, and in the meanwhile see how far the code I conjured can go, now well aware it is an imperfect, unreliable solution.
Let me know if there is anything else I can do.

[yuri]

I meant that it's not loaded from within the Email entity but externally and then the value assigned to the entity. There is also the problem of value actuality and the problem of performance.