diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index e48ed01fc21..4398da516cf 100644
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -462,6 +462,11 @@ need to be adapted. See :issue:`27819` for more details.
 email
 -----
 
+The new email API, enabled via the *policy* keyword to various constructors, is
+no longer provisional.  The :mod:`email` documentation has been reorganized and
+rewritten to focus on the new API, while retaining the old documentation for
+the legacy API.  (Contributed by R. David Murray in :issue:`24277`.)
+
 The :mod:`email.mime` classes now all accept an optional *policy* keyword.
 (Contributed by Berker Peksag in :issue:`27331`.)
 
diff --git a/Misc/NEWS b/Misc/NEWS
index 726461590b4..c60e8708034 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -99,6 +99,9 @@ Core and Builtins
 Library
 -------
 
+- Issue #24277: The new email API is no longer provisional, and the docs
+  have been reorganized and rewritten to emphasize the new API.
+
 - lib2to3.pgen3.driver.load_grammar() now creates a stable cache file
   between runs given the same Grammar.txt input regardless of the hash
   randomization setting.