SMTP mail arrives in Textpattern (finally!)

Bloke · 2021-02-15 18:49:18

From this commit onwards in the forthcoming Textpattern 4.9.0, we now have built-in support for sending messages via third-party email systems. This should hugely cut down on issues of undeliverability when sending from an own-domain because messages can be relayed via services like gmail or MailJet or SendGrid or whatever service you like (subject to you approving the domain for sending).

The settings haven’t yet had strings applied so it’s a little messy, but the principle is this:

Visit Admin->Preferences.
Open up the new ‘Mail’ sub area.
Enable the ‘Use enhanced mail features’ radio button. This exposes a bunch of settings for you to play with:
1. SMTP host: Your third-party relay server.
2. SMTP port: The port that your third-party relay server uses to accept mail.
3. SMTP user: The username to log into the mail system.
4. SMTP pass: The password used to gain access to the mail system.
5. SMTP security method: The type of security that the host expects (SSL by default, but some require TLS). You can specify none but it’s not recommended for online servers. Fine for local dev emails.

Most providers will play by the rules and do things properly. Except GoDaddy. To get it to relay via them on your hosting package, you need the following settings:

SMTP Host: localhost
SMTP Port: 25
SMTP User and Pass: leave empty
SMTP Security method: None

Don’t ask. I’ve not tested this as I’m not hosting with them so please test if you can. And this is a general call to test it with as many different sending systems as you can to check we have enough flexibility in the prefs.

Speaking of which, because this is potentially sensitive information you may wish to keep from other Publishers/Managing Editors, if you prefer you may define the SMTP parameters in your config.php instead of in the Prefs panel. To do this add any/all of the following lines to your config.php:

define('SMTP_HOST', 'example.org');
define('SMTP_PORT', '456');
define('SMTP_USER', 'donald@example.org');
define('SMTP_PASS', 'DonaldSwainIsKing!');
define('SMTP_SECTYPE', 'tls');

Any parameters you define in config.php will not be shown in the UI and the corresponding UI field will be disabled.

If you have your site in Testing or Debugging mode then every request will automatically be logged to your Txp tempdir in a file called txp_smtp.log. More verbose output in Debugging mode. This feature may be removed in future. Not sure if it’s a good idea or not. Thoughts welcome.

Much more goodness to come. I need to wire it up so messages are displayed in the current UI language and intend to expose some more advanced config.php params to enable you to sign messages or implement DKIM for even greater message trustworthiness. Plus support HTML emails somehow.

For now, please go and play with it and post any feedback here so this can be improved. New account notifications and password reset requests will automatically be routed according to your prefs. Further jobs include patching com_connect to use it too.

If you want to play with your own messages, you can make a Form or an article (turn off Textile!) and do something like this in the body:

<txp:php>
$msg = Txp::get('\Textpattern\Mail\Compose')->getDefaultAdapter();
$msg->body("I'm a test message.")
->subject("Test message via PHPMailer")
->replyTo("reply-to@example.com", "Mr Nobody")
->from("whoever@example.com")
->to("recipient@example.org")
->cc("carbon@example.org", "Karbon Kopy");
$msg->send();
</txp:php>

View your article and your message will be sent. Enjoy!

jakob · 2021-02-15 20:17:03

Cool!

In case it’s of interest to anyone: I tried a preliminary version of this at the weekend using HELO to catch outgoing email sent by my local webserver on my computer and it worked a treat.

HELO

For HELO you need:

smtp_host: 127.0.0.1
smtp_port: 2525
smtp_user: {Mailbox name, e.g. your site's name*}
smtp_pass: {leave empty}
smtp_sectype: {leave empty}

I also had to set smtp_from to my email name (but that may no longer be necessary with Stef’s current variant).

The emails are then readable in the HELO app. If you specify a mailbox name. the emails will be grouped in inboxes using the mailbox name you specified. That can help if you test many sites locally and want to keep email messages apart.

———

MailHog

Another tool for catching outgoing emails from local webservers for testing purposes is Mailhog. It is open-source, written in Go(lang) but I unfortunately had no luck installing it. The following should work for Mailhog but are untested:

smtp_host: 127.0.0.1
smtp_port: 1025
smtp_user: {leave empty}
smtp_pass: {leave empty}
smtp_sectype: {leave empty}

With the standard settings, the web user interface for reading the sent emails is reachable at: http://localhost:8025.

———

MailDev

Yet another tool for testing local web development email is MailDev. It is also open-source, based on Node. The following settings should work for MailDev but are also untested:

smtp_host: 127.0.0.1
smtp_port: 1025
smtp_user: {leave empty}
smtp_pass: {leave empty}
smtp_sectype: {leave empty}

With the standard settings, the web user interface for reading the sent emails is reachable at: http://localhost:1080.

———

Thanks Stef!

*For info: in most operating systems localhost and 127.0.0.1 can be used interchangeably.

Bloke · 2021-02-15 20:54:51

You’re welcome. Been a long time coming.

I’d love to find out if this works okay in a localhost environment because, as you say, that’s another bonus where you can intercept outbound mail for testing.

At the moment, if you specify a username it switches SMTPAuth on. If you omit it, that flag stays off. This allows you to leave the password blank (because it’s a legitimate use case to have an authentication mechanism with no password) and I think this works.

The upshot is that I haven’t exposed the SMTPAuth value directly as an option so it’s reliant on you specifying the username or not. It’s the same with SMTPAutoTLS. That’s switched on automatically for you if you choose TLS or SSL, and turned off when you set None (as well as automatically setting options to not verify SSL peers and stuff like that so it doesn’t complain if you don’t have certs in place).

My hope is that these conventions will be sensible enough that we won’t need to expose these extended options as prefs or overridable config params. But we’ll only know that by extensively testing this on as many servers and environments as possible – local and online.

Bloke · 2021-02-16 00:14:52

Update

1. Languages are now supported for error messages.

2. You can configure DKIM parameters in config.php to assert the identity of the sending domain. This is done via a bunch of define() parameters as follows:

// This should match the domain of your From address.
define('DKIM_DOMAIN', 'example.com');

// The selector.
define('DKIM_SELECTOR', 'mailer');

// The identity you're signing as - usually your From address.
// You can use {SMTP_FROM} or {SMTP_REPLY_TO} as a replacement to
// use that value from the message instead of hard-coding a value.
define('DKIM_IDENTITY', '{SMTP_FROM}');

// Path to your private key.
define('DKIM_PRIVATE', '/path/to/dkim_private.pem');

// Your private key's passphrase, if it has one.
define('DKIM_PASSPHRASE', 'pass-phrase-here');

// Suppress listing signed header fields in signature. Defaults to true for debugging purposes.
define('DKIM_COPYHEADERFIELDS', false);

It’s assumed you’ve already set up a key pair and have located the relevant key file(s) on your server.

3. If you wish to digitally sign your message with your certificate to guarantee authenticity, you may do so by supplying a single array of certificate info in config.php as follows:

define('SMTP_CERT_INFO', array(
   'certfile'  => '/path/to/cert.crt',
   'pkfile'    => '/path/to/cert.key',
   'pkpass'    => 'optionalPrivateKeyPassword',
   'certchain' => '/path/to/certchain.pem',
));

Again, it is assumed you’ve generated all the necessary public key pairs and installed the private key and chain files in the locations given above. Note the password is the one you protected your private key with (not the Import Password!). You can omit this if you don’t have a password to unlock your private key.

If anyone fancies taking this for a test-drive, please do and post your feedback here. Thank you.

amordecosmos · 2021-02-16 17:34:42

Thank you! This is timely for me but also may have been a future deal breaker for new Textpatterners.

Bloke · 2021-02-16 17:40:31

Glad it’ll be useful. Looking forward to feedback and figuring out how to allow people to supply HTML and plaintext content.

And yeah, should have done this ages ago.

philwareham · 2021-10-15 10:00:03

Hi Stef, does this work with com_connect (i.e. does that plugin go through Textpatterns internal emailing routing)?

My website has stopped sending emails from enquiries using the com_connect form (might have stopped a fair while back without me realising) and I’d like to use SendGrid to send them in future (as I already do for another app on our server).

I’d also need to run Textpattern 4.9 on a production server which makes me slightly nervous.

Bloke · 2021-10-15 10:04:13

It doesn’t (yet) as it needs to be refactored to pick up the hosting details from core. I do however have a version knocking around somewhere which uses PHPMailer internally to the plugin. I could dig that out for you a stop-gap?

philwareham · 2021-10-15 10:08:41

Bloke wrote #331797:

I do however have a version knocking around somewhere which uses PHPMailer internally to the plugin. I could dig that out for you a stop-gap?

Oohh, yes please. That would be most helpful!

philwareham · 2021-10-15 11:05:43

philwareham wrote #331798:

Oohh, yes please. That would be most helpful!

Actually, I got this working again with the standard com_connect and some updated SPF, DKIM and DMARC settings in our DNS, plus some whitelisting – so no worries! Thanks anyway Stef.

JimJoe · 2023-12-08 19:27:44

namecheap also does this. I just got bit by it. Does this work with txp 4.8.8 ?

Thanks for the info.

Bloke · 2023-12-08 19:55:37

Sadly not. You’d need 4.9-dev to work with the 4.9 branch of com_connect which takes advantage of core’s mail handling options.

Textpattern CMS

Textpattern CMS support forum

#1 2021-02-15 18:49:18