Fix: constrain image sizes in email notifications

[faisalahammad]

Fixes #3529

Proposed changes:

• Email notifications currently size avatars and post images with CSS only. That CSS is injected mid-body by the embed, and desktop email clients frequently strip or ignore it, so a remote user with a large avatar renders the image at native size and pushes the message off screen.
• Added explicit width/height attributes to the embed avatar (48px) and the new follower icon (64px). The size now holds in the email client even when the style blocks are stripped, which is exactly the case the attributes target. When the CSS does load, the existing rules still apply without the inline version duplicating them.
• Added width="600" to the embed preview images. With the CSS loaded the .ap-preview img grid sizing takes over; without it the browser keeps the aspect ratio from the width instead of squashing the image.
• Added a global img { max-width: 100%; height: auto; } rule to the shared email header style block. This does not fix the avatar (a client that strips the embed style block strips this one too) but it does constrain images inside the remote post content, such as custom emoji, that no selector covers today.

Other information:

• Have you written new tests for your changes, if applicable?

Logged-in test of email templates can't be automated here, so the fix was verified against the repository CSS and template output. The changes are template and CSS-only with no logic change, so no PHPUnit coverage is added.

Testing instructions:

• Set up a local environment and install the plugin (npm run env-start).
• Receive a direct message or mention from a remote account whose avatar is larger than 48px, and open the resulting email in a client that strips <style> blocks (for example Gmail).
• Confirm the avatar now renders at 48px instead of its native size and the message content stays within the email width.
• Trigger a new follower email from an account with a large icon and confirm the icon is 64px.
• Check a public post with attachments still shows the 48px avatar and full-width preview grid in the embed (regression check).

Changelog entry

• Automatically create a changelog entry from the details below.

A changelog entry was added manually as .github/changelog/3529-avatar-email-max-width.

Changelog Entry Details

Significance

• Patch
• Minor
• Major

Type

• Added - for changes in existing functionality
• Changed - for changes in existing functionality
• Deprecated - for soon-to-be removed features
• Removed - for now removed features
• Fixed - for any bug fixes
• Security - in case of vulnerabilities

Message

Fixed oversized avatar and post images in email notifications from remote users. Avatars and inline images now resize to fit the email width instead of overflowing the screen.

[pfefferle]

I am not sure if this pr fixes the issue properly. The report is about a mention, and it shows an avatar that is already around 100% max but this full display size is already too big. I think your PR is a nice improvement, but the issue is still existent!?

[faisalahammad]

@pfefferle thanks for the feedback. I checked the mention path (new-dm and new-mention both render the embed) and found two things that were still missing.

The avatar in templates/embed.php now has inline style="max-width:48px; border-radius:50%;" in addition to the width="48" height="48" attributes. The inline max-width covers clients that strip the style block, so the avatar stays at 48px instead of rendering at native size.

The featured post image in templates/embed.php now has width="600" height="338" and style="max-width:100%;". That is the image that overflows in the screenshot. It now fits the email width in CSS-stripped clients.

I kept height:auto out of the inline styles on purpose. The embed template is also used for the web oEmbed output, and inline height:auto would override the grid object-fit: cover layout there. So the email fix uses the global img { max-width: 100%; } rule plus the explicit dimensions, and the web context is unchanged.

Commit: 0bf2ae5

Would appreciate your review of this follow-up when you have a chance.

[pfefferle]

Thanks for looking into the mention path, max-width:48px is the bit I was missing. 100% of a 600px container is still 600px, so that really was the problem.

Two things block this, plus one preference.

The changelog file sits in a subfolder, and changelogger only reads flat files in .github/changelog/, so the entry gets lost. And height="338" is a guessed aspect ratio that breaks exactly in the case this PR is about.

The preference: I would like to avoid inline style attributes here. templates/embed.php is the public oEmbed template, not a mail template, and inline styles beat assets/css/activitypub-embed.css silently. The width/height attributes already do the work when the style block is stripped, so I think we can get away without any inline style at all.

One note on the reasoning in the description: templates/emails/parts/header.php prints a <style> block too, in the same mail body as the embed one. A client that strips style blocks strips both. So the header rule is not what fixes the avatar, the attributes are. It is still useful for images inside the remote content, custom emoji and such, but the description credits it for the wrong thing.

Branch is a bit behind trunk, needs a rebase before merge.

[Copilot]

Pull request overview

This PR addresses email client rendering issues where remote avatars and embedded post images can appear at their native (often oversized) dimensions when <style> blocks are stripped or ignored, by adding explicit image sizing attributes and a defensive global email image rule.

Changes:

• Added explicit width/height attributes for avatar and follower icon images to keep sizes stable without CSS.
• Added a width="600" attribute for embedded preview images to preserve aspect ratio and avoid overflow in CSS-stripping clients.
• Added a global img { max-width: 100%; height: auto; } rule to the shared email header styles to constrain inline content images.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
templates/embed.php	Adds explicit sizing attributes for embed avatar (48×48) and preview images (600px width).
templates/emails/parts/header.php	Adds a global img rule to constrain inline images inside email HTML.
templates/emails/new-follower.php	Adds explicit sizing attributes for follower icon (64×64).
.github/changelog/3529-avatar-email-max-width	Adds a patch-level changelog entry documenting the email image sizing fix.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[pfefferle]

All five points are in the diff now, not just in the replies. The changelog file is flat, so changelogger actually reads it. The guessed height="338" is gone and width="600" alone keeps the aspect ratio when the style block is stripped, and with the CSS loaded .ap-preview img overrides it anyway. Inline styles are dropped everywhere, so the embed avatar and the follower icon now behave the same when the styles are gone.

One thing you do not need to worry about: the description has both the auto-changelog checkbox checked and a manual file. The workflow skips the body parsing when a changelog file is there, so there is no duplicate entry.

Only the rebase is left, the branch is one commit behind trunk. Good to merge after that.

Thanks a lot @faisalahammad!

[pfefferle]

Maybe I was not precise... You would have to rebase your branch and push the updates @faisalahammad ☺️

[faisalahammad]

Rebased the branch on current trunk and pushed. No conflicts. Template and changelog content is unchanged from the version you approved, only the base moved. Checks are rerunning now.

Ready for re-review when you have a moment.

[faisalahammad]

Branch updated again, rebased on the latest trunk (includes the podcast federation change). Same three commits, no content changes. Checks are rerunning.