All APIM email notifications failing — “Provided template body is not a well-formed HTML document

Question

All APIM email notifications failing — “Provided template body is not a well-formed HTML document

Mallelin Bolufe 0

Hello Microsoft Support,

We are experiencing an issue where none of the email notifications in Azure API Management (APIM) are being sent — this includes all default notification types (sign-up confirmations, subscription requests, etc.).

When reviewing the notification templates in the Azure Portal under Notifications > Templates, we consistently receive the following error in all of our templates:

"Provided template body is not a well-formed HTML document"

<!DOCTYPE html>
<html lang="en">
  <head>
  </head>
  <body>
    <p style="font-size:12pt;font-family:'Segoe UI'">Dear $DevFirstName $DevLastName,</p>
    <p style="font-size:12pt;font-family:'Segoe UI'">
      Thank you for your interest in our <strong>$ProdName</strong> API product!
    </p>
    <p style="font-size:12pt;font-family:'Segoe UI'">
      We were delighted to receive your subscription request. We will promptly review it and get back to you at <strong>$DevEmail</strong>.
    </p>
    <p style="font-size:12pt;font-family:'Segoe UI'">Thank you,</p>
    <p style="font-size:12pt;font-family:'Segoe UI'">The $OrganizationName API Team</p>
    <p><a style="font-size:12pt;font-family:'Segoe UI'" href="http://$DevPortalUrl">$DevPortalUrl</a></p>
  </body>
</html>

However, we’ve validated the HTML for multiple templates using W3C and other HTML validators and confirmed that:

The templates contain complete, well-structured HTML documents (<!DOCTYPE html>, <html>, <head>, <body>)

No syntax issues, broken tags, or empty elements are present

What we’ve done so far:

Verified SMTP settings are correctly configured under Notifications > Email
Enabled diagnostic logs, but AzureDiagnostics shows no log entries for email or notification-related activity

Our Questions:

What conditions might cause the “not a well-formed HTML document” error even when the HTML is valid?
Is there any internal validation mechanism in APIM that might be rejecting standard HTML5 syntax (e.g., <meta charset="UTF-8">, <head></head>)?
Could there be a regression or platform-side validation issue affecting all templates?
Is there a way to obtain deeper diagnostic logs or traces showing template rendering or notification delivery attempts?

Any guidance or escalation would be greatly appreciated, as this issue is blocking all APIM-generated communication.

Thank you

Sai Prabhu Naveen Parimi 2,420 Reputation points Microsoft External Staff Moderator

2025-06-19T17:58:02.51+00:00
@Mallelin Bolufe

It looks like you're facing an issue with Azure API Management where none of your email notifications are being sent due to the error: “Provided template body is not a well-formed HTML document.

1.Can you simplify the HTML template to see if a basic version sends without errors?

Have you tested with different content types or styles beyond standard HTML (e.g., inline CSS)?
Mallelin Bolufe 0 Reputation points

2025-06-19T18:14:13.1333333+00:00

I’m able to update the email template with a simplified HTML without any issues. However, the error message "Provided template body is not a well-formed HTML document" still appears in the Azure Portal UI for that template.
Deleted

This comment has been deleted due to a violation of our Code of Conduct. The comment was manually reported or identified through automated detection before action was taken. Please refer to our Code of Conduct for more information.
Sai Prabhu Naveen Parimi 2,420 Reputation points Microsoft External Staff Moderator

2025-06-19T18:22:11.95+00:00
@Mallelin Bolufe

Thanks for sharing the issue regarding the email templates in Azure API Management showing the error:

“Provided template body is not a well-formed HTML document”

Here’s a quick workaround that has helped in similar cases:

Please make sure the <head> section in your HTML is not empty. You can add something simple like this:

<head> <meta charset="UTF-8"> <title>Notification</title> </head>

This should remove the error message and allow the email to function properly.
Mallelin Bolufe 0 Reputation points

2025-06-19T18:33:49.6933333+00:00
I added the <head> element as per your suggestion, but it returns an error when I try to save the template: I changed :

<meta charset="UTF-8">

to:

<meta charset="UTF-8"/>

And I was able to save, but still, the error is showing:
Sai Prabhu Naveen Parimi 2,420 Reputation points Microsoft External Staff Moderator

2025-06-19T18:37:46.6666667+00:00

@Mallelin Bolufe

Thanks for the update.

If the portal still shows the “not a well-formed HTML document” error, here are a few quick workarounds to try:

Add a <title> and basic <style> inside the <head> tag

Remove <!DOCTYPE html> from the top

Temporarily replace variables like $DevFirstName with static text

Try updating the template via REST API instead of the portal

Let me know if you'd like help trying any of these.
Sai Prabhu Naveen Parimi 2,420 Reputation points Microsoft External Staff Moderator

2025-06-20T23:22:31.7933333+00:00

@Mallelin Bolufe

Following up to see if you have a chance to check the previous response and let me know if you have any further questions on this.
Sai Prabhu Naveen Parimi 2,420 Reputation points Microsoft External Staff Moderator

2025-06-24T03:06:42.1266667+00:00

@Mallelin Bolufe

Just following up to see if you had a chance to review the information shared earlier. Please let me know if everything is working as expected or if you need any further assistance.

1 answer

Your answer

Sai Prabhu Naveen Parimi 2,420 Reputation points Microsoft External Staff Moderator

2025-06-19T17:58:02.51+00:00

@Mallelin Bolufe

It looks like you're facing an issue with Azure API Management where none of your email notifications are being sent due to the error: “Provided template body is not a well-formed HTML document.

1.Can you simplify the HTML template to see if a basic version sends without errors?

Have you tested with different content types or styles beyond standard HTML (e.g., inline CSS)?
Mallelin Bolufe 0 Reputation points

2025-06-19T18:14:13.1333333+00:00

I’m able to update the email template with a simplified HTML without any issues. However, the error message "Provided template body is not a well-formed HTML document" still appears in the Azure Portal UI for that template.
Deleted

This comment has been deleted due to a violation of our Code of Conduct. The comment was manually reported or identified through automated detection before action was taken. Please refer to our Code of Conduct for more information.
Sai Prabhu Naveen Parimi 2,420 Reputation points Microsoft External Staff Moderator

2025-06-19T18:22:11.95+00:00

@Mallelin Bolufe

Thanks for sharing the issue regarding the email templates in Azure API Management showing the error:

“Provided template body is not a well-formed HTML document”

Here’s a quick workaround that has helped in similar cases:

Please make sure the <head> section in your HTML is not empty. You can add something simple like this:

<head> <meta charset="UTF-8"> <title>Notification</title> </head>

This should remove the error message and allow the email to function properly.
Mallelin Bolufe 0 Reputation points

2025-06-19T18:33:49.6933333+00:00

I added the <head> element as per your suggestion, but it returns an error when I try to save the template: I changed :

<meta charset="UTF-8">

to:

<meta charset="UTF-8"/>

And I was able to save, but still, the error is showing:
Sai Prabhu Naveen Parimi 2,420 Reputation points Microsoft External Staff Moderator

2025-06-19T18:37:46.6666667+00:00

@Mallelin Bolufe

Thanks for the update.

If the portal still shows the “not a well-formed HTML document” error, here are a few quick workarounds to try:

Add a <title> and basic <style> inside the <head> tag

Remove <!DOCTYPE html> from the top

Temporarily replace variables like $DevFirstName with static text

Try updating the template via REST API instead of the portal

Let me know if you'd like help trying any of these.
Sai Prabhu Naveen Parimi 2,420 Reputation points Microsoft External Staff Moderator

2025-06-20T23:22:31.7933333+00:00

@Mallelin Bolufe

Following up to see if you have a chance to check the previous response and let me know if you have any further questions on this.
Sai Prabhu Naveen Parimi 2,420 Reputation points Microsoft External Staff Moderator

2025-06-24T03:06:42.1266667+00:00

@Mallelin Bolufe

Just following up to see if you had a chance to review the information shared earlier. Please let me know if everything is working as expected or if you need any further assistance.

Answer 1

Mallelin Bolufe 0

We confirmed with the Microsoft product group that the email validation error is a known bug, and a fix is already being rolled out. They’ve applied a patch across the Government Cloud. While I’m still seeing the error message, the good news is that we’re now receiving email notifications.

Share via

All APIM email notifications failing — “Provided template body is not a well-formed HTML document

1 answer

Your answer