From fa43bf850aa3d304d8b631214a91cb9386207cc0 Mon Sep 17 00:00:00 2001 From: Vasiliy Kiryanov Date: Sat, 7 Nov 2026 17:33:08 -0500 Subject: [PATCH] gh-80274: Add smtputf8 parameter to smtplib.SMTP.verify() and expn() --- Doc/library/smtplib.rst | 42 +++++- Doc/whatsnew/3.16.rst | 9 ++ Lib/smtplib.py | 46 +++++- Lib/test/test_smtplib.py | 134 +++++++++++++++++- ...6-11-07-17-23-45.gh-issue-80274.6HZDIk.rst | 3 + 5 files changed, 221 insertions(+), 13 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2026-11-07-17-23-45.gh-issue-80274.6HZDIk.rst diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 5c97199bc453e8..1e352544692c23 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -320,17 +320,57 @@ An :class:`SMTP` instance has the following methods: by the server, :const:`False` otherwise. Case is ignored. -.. method:: SMTP.verify(address) +.. method:: SMTP.verify(address, *, smtputf8=False) Check the validity of an address on this server using SMTP ``VRFY``. Returns a tuple consisting of code 250 and a full :rfc:`822` address (including human name) if the user address is valid. Otherwise returns an SMTP error code of 400 or greater and an error string. + If *smtputf8* is true, the address is sent as UTF-8 together with the + ``SMTPUTF8`` parameter (:rfc:`6531`), which also allows UTF-8 in the reply. + In that case, if there has been no previous ``EHLO`` or ``HELO`` command + this session, this method tries ESMTP ``EHLO`` first. + + This method may raise the following exceptions: + + :exc:`SMTPNotSupportedError` + *smtputf8* is true but the ``SMTPUTF8`` extension is not supported by + the server. + .. note:: Many sites disable SMTP ``VRFY`` in order to foil spammers. + .. versionchanged:: next + Added the *smtputf8* parameter. + + +.. method:: SMTP.expn(address, *, smtputf8=False) + + Expand a mailing list on this server using SMTP ``EXPN``. Returns a tuple + consisting of code 250 and the members of the list, one full :rfc:`822` + address (including human name) per line, if the list exists. Otherwise + returns an SMTP error code of 400 or greater and an error string. + + If *smtputf8* is true, the list name is sent as UTF-8 together with the + ``SMTPUTF8`` parameter (:rfc:`6531`), which also allows UTF-8 in the reply. + In that case, if there has been no previous ``EHLO`` or ``HELO`` command + this session, this method tries ESMTP ``EHLO`` first. + + This method may raise the following exceptions: + + :exc:`SMTPNotSupportedError` + *smtputf8* is true but the ``SMTPUTF8`` extension is not supported by + the server. + + .. note:: + + Many sites disable SMTP ``EXPN`` in order to foil spammers. + + .. versionchanged:: next + Added the *smtputf8* parameter. + .. method:: SMTP.login(user, password, *, initial_response_ok=True) diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst index 4af5d3c0bd072e..dec45daa94becc 100644 --- a/Doc/whatsnew/3.16.rst +++ b/Doc/whatsnew/3.16.rst @@ -688,6 +688,15 @@ shutil (Contributed by Emma Harper Smith and Stan Ulbrych in :gh:`84027`.) +smtplib +------- + +* Add the *smtputf8* parameter to :meth:`~smtplib.SMTP.verify` and + :meth:`~smtplib.SMTP.expn` to send non-ASCII addresses to servers that + support the ``SMTPUTF8`` extension (:rfc:`6531`). + (Contributed by Vasiliy Kiryanov in :gh:`80274`.) + + socket ------ diff --git a/Lib/smtplib.py b/Lib/smtplib.py index 4cfc2338d99c67..ce620b3a68dcf2 100644 --- a/Lib/smtplib.py +++ b/Lib/smtplib.py @@ -589,16 +589,50 @@ def data(self, msg): self._print_debug('data:', (code, msg)) return (code, msg) - def verify(self, address): - """SMTP 'verify' command -- checks for address validity.""" - self.putcmd("vrfy", _addr_only(address)) + def _putcmd_addr(self, cmd, address, smtputf8): + """Send an address command (VRFY or EXPN) to the server. + + If 'smtputf8' is true, send the address as UTF-8 together with the + SMTPUTF8 parameter. + """ + address = _addr_only(address) + if smtputf8: + self.ehlo_or_helo_if_needed() + if not self.has_extn('smtputf8'): + raise SMTPNotSupportedError('SMTPUTF8 not supported by server') + # RFC 6531 section 3.7.4.2: the argument may be UTF-8, and the + # SMTPUTF8 parameter allows UTF-8 in the reply. + command_encoding = self.command_encoding + self.command_encoding = 'utf-8' + try: + self.putcmd(cmd, f'{address} SMTPUTF8') + finally: + self.command_encoding = command_encoding + else: + self.putcmd(cmd, address) + + def verify(self, address, *, smtputf8=False): + """SMTP 'verify' command - checks for address validity. + + If 'smtputf8' is true, send the address as UTF-8 together with the + SMTPUTF8 parameter (per RFC 6531), which also allows UTF-8 in the + reply. In that case, if there has been no previous EHLO or HELO + command this session, this method tries ESMTP EHLO first. + """ + self._putcmd_addr("vrfy", address, smtputf8) return self.getreply() # a.k.a. vrfy = verify - def expn(self, address): - """SMTP 'expn' command -- expands a mailing list.""" - self.putcmd("expn", _addr_only(address)) + def expn(self, address, *, smtputf8=False): + """SMTP 'expn' command - expands a mailing list. + + If 'smtputf8' is true, send the list name as UTF-8 together with the + SMTPUTF8 parameter (per RFC 6531), which also allows UTF-8 in the + reply. In that case, if there has been no previous EHLO or HELO + command this session, this method tries ESMTP EHLO first. + """ + self._putcmd_addr("expn", address, smtputf8) return self.getreply() # some useful methods diff --git a/Lib/test/test_smtplib.py b/Lib/test/test_smtplib.py index b8aac8c20202a2..49427de21979a4 100644 --- a/Lib/test/test_smtplib.py +++ b/Lib/test/test_smtplib.py @@ -806,6 +806,7 @@ def testLineTooLong(self): 'Ms.B@xn--fo-fka.com':'Sally B', 'Mrs.C@somewhereesle.com':'Ruth C', } +sim_utf8_users = {'Ms.É@somewhere.com': 'Éva É'} sim_auth = ('Mr.A@somewhere.com', 'somepassword') sim_cram_md5_challenge = ('PENCeUxFREJoU0NnbmhNWitOMjNGNn' @@ -813,6 +814,7 @@ def testLineTooLong(self): sim_lists = {'list-1':['Mr.A@somewhere.com','Mrs.C@somewhereesle.com'], 'list-2':['Ms.B@xn--fo-fka.com',], } +sim_utf8_lists = {'list-é': ['Mr.A@somewhere.com', 'Ms.É@somewhere.com']} # Simulated SMTP channel & server class ResponseException(Exception): pass @@ -949,23 +951,39 @@ def smtp_EHLO(self, arg): self.seen_greeting = arg self.extended_smtp = True + def _strip_smtputf8(self, arg): + # RFC 6531 section 3.7.4.2: VRFY and EXPN take an optional SMTPUTF8 + # parameter which allows UTF-8 in the reply. + if not arg: + return arg + arg, _, params = arg.partition(' ') + params = self._getparams(params.upper().split()) + if params and params.pop('SMTPUTF8', False) is True: + self.require_SMTPUTF8 = True + return arg + def smtp_VRFY(self, arg): # For max compatibility smtplib should be sending the raw address. - if arg in sim_users: - self.push('250 %s %s' % (sim_users[arg], smtplib.quoteaddr(arg))) + arg = self._strip_smtputf8(arg) + users = sim_users | sim_utf8_users + if arg in users: + self.push('250 %s %s' % (users[arg], smtplib.quoteaddr(arg))) else: self.push('550 No such user: %s' % arg) def smtp_EXPN(self, arg): + arg = self._strip_smtputf8(arg) list_name = arg.lower() - if list_name in sim_lists: - user_list = sim_lists[list_name] + lists = sim_lists | sim_utf8_lists + users = sim_users | sim_utf8_users + if list_name in lists: + user_list = lists[list_name] for n, user_email in enumerate(user_list): quoted_addr = smtplib.quoteaddr(user_email) if n < len(user_list) - 1: - self.push('250-%s %s' % (sim_users[user_email], quoted_addr)) + self.push('250-%s %s' % (users[user_email], quoted_addr)) else: - self.push('250 %s %s' % (sim_users[user_email], quoted_addr)) + self.push('250 %s %s' % (users[user_email], quoted_addr)) else: self.push('550 No access for you!') @@ -1357,6 +1375,40 @@ def test_send_unicode_without_SMTPUTF8(self): self.addCleanup(smtp.close) self.assertRaises(UnicodeEncodeError, smtp.sendmail, 'Alice', 'Böb', '') self.assertRaises(UnicodeEncodeError, smtp.mail, 'Älice') + self.assertRaises(UnicodeEncodeError, smtp.verify, 'Ms.É@somewhere.com') + self.assertRaises(UnicodeEncodeError, smtp.expn, 'list-é') + + def test_vrfy_NotSupportedError_if_no_SMTPUTF8(self): + smtp = smtplib.SMTP( + HOST, self.port, local_hostname='localhost', + timeout=support.LOOPBACK_TIMEOUT) + self.addCleanup(smtp.close) + + smtp.ehlo() + self.assertFalse(smtp.has_extn('smtputf8')) + with self.assertRaises(smtplib.SMTPNotSupportedError): + smtp.vrfy('Mr.A@somewhere.com', smtputf8=True) + with self.assertRaises(smtplib.SMTPNotSupportedError): + smtp.vrfy('Ms.É@somewhere.com', smtputf8=True) + + # Nothing was sent, the connection is still usable + self.assertEqual(smtp.noop(), (250, b'OK')) + + def test_expn_NotSupportedError_if_no_SMTPUTF8(self): + smtp = smtplib.SMTP( + HOST, self.port, local_hostname='localhost', + timeout=support.LOOPBACK_TIMEOUT) + self.addCleanup(smtp.close) + + smtp.ehlo() + self.assertFalse(smtp.has_extn('smtputf8')) + with self.assertRaises(smtplib.SMTPNotSupportedError): + smtp.expn('list-1', smtputf8=True) + with self.assertRaises(smtplib.SMTPNotSupportedError): + smtp.expn('list-é', smtputf8=True) + + # Nothing was sent, the connection is still usable + self.assertEqual(smtp.noop(), (250, b'OK')) def test_send_message_error_on_non_ascii_addrs_if_no_smtputf8(self): # This test is located here and not in the SMTPUTF8SimTests @@ -1485,6 +1537,76 @@ def test_send_unicode_with_SMTPUTF8_via_sendmail(self): self.assertIn('SMTPUTF8', self.serv.last_mail_options) self.assertEqual(self.serv.last_rcpt_options, []) + def test_vrfy_with_SMTPUTF8(self): + smtp = smtplib.SMTP( + HOST, self.port, local_hostname='localhost', + timeout=support.LOOPBACK_TIMEOUT) + self.addCleanup(smtp.close) + + smtp.ehlo() + self.assertTrue(smtp.has_extn('smtputf8')) + self.assertEqual( + smtp.vrfy('Ms.É@somewhere.com', smtputf8=True), + (250, 'Éva É '.encode('utf-8')) + ) + # ASCII reply + self.assertEqual( + smtp.vrfy('Mr.A@somewhere.com', smtputf8=True), + (250, b'John A ') + ) + # encoding doesn't leak out of a command + self.assertEqual(smtp.command_encoding, 'ascii') + self.assertEqual( + smtp.vrfy('unknown@unknown.com', smtputf8=True), + (550, b'No such user: unknown@unknown.com') + ) + # Reply stream still in sync + self.assertEqual(smtp.noop(), (250, b'OK')) + + def test_vrfy_smtputf8_ehlo_if_needed(self): + smtp = smtplib.SMTP( + HOST, self.port, local_hostname='localhost', + timeout=support.LOOPBACK_TIMEOUT) + self.addCleanup(smtp.close) + + self.assertEqual( + smtp.vrfy('Ms.É@somewhere.com', smtputf8=True), + (250, 'Éva É '.encode('utf-8')) + ) + self.assertTrue(smtp.has_extn('smtputf8')) + # No reply was left unread + self.assertEqual(smtp.noop(), (250, b'OK')) + + def test_vrfy_smtputf8_helo_fails(self): + smtp = smtplib.SMTP( + HOST, self.port, local_hostname='localhost', + timeout=support.LOOPBACK_TIMEOUT) + self.addCleanup(smtp.close) + + smtp.helo() + with self.assertRaises(smtplib.SMTPNotSupportedError): + smtp.vrfy('Mr.A@somewhere.com', smtputf8=True) + self.assertFalse(smtp.has_extn('smtputf8')) + # Nothing was sent, the connection is still usable + self.assertEqual(smtp.noop(), (250, b'OK')) + + def test_expn_with_SMTPUTF8(self): + smtp = smtplib.SMTP( + HOST, self.port, local_hostname='localhost', + timeout=support.LOOPBACK_TIMEOUT) + self.addCleanup(smtp.close) + + smtp.ehlo() + self.assertTrue(smtp.has_extn('smtputf8')) + self.assertEqual( + smtp.expn('list-é', smtputf8=True), + (250, ('John A \n' + 'Éva É ').encode('utf-8'))) + # Encoding doesn't leak out of a command + self.assertEqual(smtp.command_encoding, 'ascii') + # No reply was left unread + self.assertEqual(smtp.noop(), (250, b'OK')) + def test_send_unicode_with_SMTPUTF8_via_low_level_API(self): m = '¡a test message containing unicode!'.encode('utf-8') smtp = smtplib.SMTP( diff --git a/Misc/NEWS.d/next/Library/2026-11-07-17-23-45.gh-issue-80274.6HZDIk.rst b/Misc/NEWS.d/next/Library/2026-11-07-17-23-45.gh-issue-80274.6HZDIk.rst new file mode 100644 index 00000000000000..f0c1a266e79c7c --- /dev/null +++ b/Misc/NEWS.d/next/Library/2026-11-07-17-23-45.gh-issue-80274.6HZDIk.rst @@ -0,0 +1,3 @@ +Add the *smtputf8* parameter to :meth:`smtplib.SMTP.verify` and +:meth:`smtplib.SMTP.expn` to send non-ASCII addresses to servers that +support the ``SMTPUTF8`` extension (:rfc:`6531`).