HtmlForgeX

API Reference

Class

EmailImage

Namespace HtmlForgeX.Email
Assembly HtmlForgeX.Email
Base Element
Implements
ILayoutAware ISpaceable<EmailImage> IRoundable<EmailImage> IRoundable

Represents an image element for email layouts with email-safe styling and attributes. Provides image display with customizable dimensions and optional embedding.

Inheritance

Constructors

EmailImage 4 overloads
public EmailImage() #

Initializes a new instance of the EmailImage class

public EmailImage(String source) #

Initializes a new instance of the EmailImage class with a source

Parameters

source System.String requiredposition: 0
The image source URL or path
public EmailImage(String source, String width, String height = "") #

Initializes a new instance of the EmailImage class with source and dimensions

Parameters

source System.String requiredposition: 0
The image source URL or path
width System.String requiredposition: 1
The image width
height System.String = "" optionalposition: 2
The image height (optional)
public EmailImage(String source, String width, String height, Boolean autoEmbed) #

Initializes a new instance of the EmailImage class with source, dimensions, and embedding option

Parameters

source System.String requiredposition: 0
The image source URL or path
width System.String requiredposition: 1
The image width
height System.String requiredposition: 2
The image height
autoEmbed System.Boolean requiredposition: 3
Whether to automatically embed the image

Methods

EmbedDarkModeImage(System.String source, System.Int32 timeoutSeconds, System.Boolean smartDetection) #

Embeds a dark mode image

Parameters

source System.String required
The dark mode image source
timeoutSeconds System.Int32 required
Timeout in seconds for URL downloads
smartDetection System.Boolean required
Whether to use smart detection

Returns

The EmailImage instance for method chaining

public EmailImage EmbedFromBase64(String base64Data, String mimeType = "image/jpeg") #
Returns: EmailImage

Embeds an image from a base64 string

Parameters

base64Data System.String requiredposition: 0
The base64 encoded image data
mimeType System.String = "image/jpeg" optionalposition: 1
The MIME type of the image

Returns

The EmailImage instance for method chaining

public EmailImage EmbedFromBytes(Byte[] imageData, String mimeType = "image/jpeg") #
Returns: EmailImage

Embeds an image from a byte array as base64

Parameters

imageData System.Byte[] requiredposition: 0
The image data as a byte array
mimeType System.String = "image/jpeg" optionalposition: 1
The MIME type of the image

Returns

The EmailImage instance for method chaining

public EmailImage EmbedFromFile(String filePath) #
Returns: EmailImage

Embeds an image from a file path as base64

Parameters

filePath System.String requiredposition: 0
The path to the image file

Returns

The EmailImage instance for method chaining

public EmailImage EmbedFromStream(Stream stream, String mimeType = "image/jpeg") #
Returns: EmailImage

Embeds an image from a stream as base64

Parameters

stream System.IO.Stream requiredposition: 0
The stream containing the image data
mimeType System.String = "image/jpeg" optionalposition: 1
The MIME type of the image

Returns

The EmailImage instance for method chaining

public EmailImage EmbedFromUrl(String url, Int32 timeoutSeconds = 30) #
Returns: EmailImage
Obsolete("Use EmbedFromUrlAsync instead.")

Embeds an image from a URL as base64.

Parameters

url System.String requiredposition: 0
The URL of the image
timeoutSeconds System.Int32 = 30 optionalposition: 1
Timeout in seconds for downloading

Returns

The EmailImage instance for method chaining

public async Task<EmailImage> EmbedFromUrlAsync(String url, Int32 timeoutSeconds = 30) #
Returns: Task<EmailImage>

Embeds an image from a URL as base64 (asynchronous)

Parameters

url System.String requiredposition: 0
The URL of the image
timeoutSeconds System.Int32 = 30 optionalposition: 1
Timeout in seconds for downloading

Returns

A task that represents the asynchronous operation

public EmailImage EmbedSmart(String source, Int32 timeoutSeconds = 30) #
Returns: EmailImage

Embeds an image smartly by detecting if it's a file path or URL

Parameters

source System.String requiredposition: 0
The image source (file path or URL)
timeoutSeconds System.Int32 = 30 optionalposition: 1
Timeout in seconds for URL downloads

Returns

The EmailImage instance for method chaining

public override Void EvaluateLayout(LayoutContext context) #
Returns: Void

Applies default border radius using layout configuration.

Parameters

context HtmlForgeX.Email.LayoutContext requiredposition: 0
Layout evaluation context.
OnAddedToDocument() #

Called when the image is added to a document

public override String ToString() #
Returns: String

Renders the email image to HTML string

Returns

HTML representation of the email image

public EmailImage WithAlignment(Alignment alignment) #
Returns: EmailImage

Sets the image alignment

Parameters

alignment HtmlForgeX.Email.Alignment requiredposition: 0
The alignment option

Returns

The EmailImage instance for method chaining

public EmailImage WithAlternativeText(String altText) #
Returns: EmailImage

Sets the alternative text for accessibility

Parameters

altText System.String requiredposition: 0
The alternative text

Returns

The EmailImage instance for method chaining

public EmailImage WithAutoEmbedding() #
Returns: EmailImage

Enables automatic image embedding

Returns

The EmailImage instance for method chaining

public EmailImage WithBorder(String border) #
Returns: EmailImage

Sets the image border

Parameters

border System.String requiredposition: 0
The border CSS value

Returns

The EmailImage instance for method chaining

public EmailImage WithBorderRadius(String borderRadius) #
Returns: EmailImage

Sets the image border radius

Parameters

borderRadius System.String requiredposition: 0
The border radius value

Returns

The EmailImage instance for method chaining

public EmailImage WithDarkModeSource(String darkSource, String darkAltText = "") #
Returns: EmailImage

Sets an alternative image source for dark mode

Parameters

darkSource System.String requiredposition: 0
The dark mode image source
darkAltText System.String = "" optionalposition: 1
Alternative text for dark mode image

Returns

The EmailImage instance for method chaining

public EmailImage WithDarkModeSwapping() #
Returns: EmailImage

Enables dark mode image swapping

Returns

The EmailImage instance for method chaining

public EmailImage WithHeight(String height) #
Returns: EmailImage

Sets the image height

Parameters

height System.String requiredposition: 0
The height value (e.g., "200px", "auto")

Returns

The EmailImage instance for method chaining

public EmailImage WithImagePair(String lightSource, String darkSource, String altText = "") #
Returns: EmailImage

Sets both light and dark mode image sources

Parameters

lightSource System.String requiredposition: 0
The light mode image source
darkSource System.String requiredposition: 1
The dark mode image source
altText System.String = "" optionalposition: 2
Alternative text for both images

Returns

The EmailImage instance for method chaining

WithMargin 3 overloads
WithMargin(HtmlForgeX.Email.EmailSpacing spacing) #

Sets uniform margin using EmailSpacing

Parameters

spacing HtmlForgeX.Email.EmailSpacing required
The spacing value

Returns

The EmailImage instance for method chaining

public EmailImage WithMargin(EmailSpacing vertical, EmailSpacing horizontal) #
Returns: EmailImage

Sets vertical and horizontal margins using EmailSpacing

Parameters

vertical HtmlForgeX.Email.EmailSpacing requiredposition: 0
The vertical spacing
horizontal HtmlForgeX.Email.EmailSpacing requiredposition: 1
The horizontal spacing

Returns

The EmailImage instance for method chaining

public EmailImage WithMargin(EmailSpacing top, EmailSpacing right, EmailSpacing bottom, EmailSpacing left) #
Returns: EmailImage

Sets individual margins for all four sides using EmailSpacing

Parameters

top HtmlForgeX.Email.EmailSpacing requiredposition: 0
The top margin
right HtmlForgeX.Email.EmailSpacing requiredposition: 1
The right margin
bottom HtmlForgeX.Email.EmailSpacing requiredposition: 2
The bottom margin
left HtmlForgeX.Email.EmailSpacing requiredposition: 3
The left margin

Returns

The EmailImage instance for method chaining

public EmailImage WithOptimization(Int32 maxWidth = 0, Int32 maxHeight = 0, Int32 quality = 85) #
Returns: EmailImage

Enables image optimization with specified parameters

Parameters

maxWidth System.Int32 = 0 optionalposition: 0
Maximum width (0 for no limit)
maxHeight System.Int32 = 0 optionalposition: 1
Maximum height (0 for no limit)
quality System.Int32 = 85 optionalposition: 2
Image quality (0-100)

Returns

The EmailImage instance for method chaining

public EmailImage WithoutAutoEmbedding() #
Returns: EmailImage

Disables automatic image embedding

Returns

The EmailImage instance for method chaining

public EmailImage WithoutDarkModeSwapping() #
Returns: EmailImage

Disables dark mode image swapping

Returns

The EmailImage instance for method chaining

public EmailImage WithoutOptimization() #
Returns: EmailImage

Disables image optimization

Returns

The EmailImage instance for method chaining

public virtual EmailImage WithRoundingMode(RoundingMode mode) #
Returns: EmailImage

Sets the rounding mode for this image.

Parameters

mode HtmlForgeX.Email.RoundingMode requiredposition: 0
Rounding mode.

Returns

The EmailImage instance for chaining.

public EmailImage WithSeparateAltTexts(String lightAltText, String darkAltText) #
Returns: EmailImage

Sets different alternative texts for light and dark mode images

Parameters

lightAltText System.String requiredposition: 0
Alternative text for light mode image
darkAltText System.String requiredposition: 1
Alternative text for dark mode image

Returns

The EmailImage instance for method chaining

WithSource 2 overloads
public EmailImage WithSource(String source, Nullable<Boolean> autoEmbed = null) #
Returns: EmailImage

Sets the image source with optional auto-embedding control

Parameters

source System.String requiredposition: 0
The image source URL or path
autoEmbed System.Nullable{System.Boolean} = null optionalposition: 1
Whether to automatically embed the image (null uses default settings)

Returns

The EmailImage instance for method chaining

public EmailImage WithSource(String source) #
Returns: EmailImage

Sets the image source

Parameters

source System.String requiredposition: 0
The image source URL or path

Returns

The EmailImage instance for method chaining

public EmailImage WithWidth(String width) #
Returns: EmailImage

Sets the image width

Parameters

width System.String requiredposition: 0
The width value (e.g., "300px", "100%")

Returns

The EmailImage instance for method chaining

Properties

public String Source { get; set; } #

Gets or sets the image source URL.

public String Width { get; set; } #

Gets or sets the image width.

public String Height { get; set; } #

Gets or sets the image height.

public String AlternativeText { get; set; } #

Gets or sets the alternative text for accessibility.

public String Alignment { get; set; } #

Gets or sets the image alignment.

public String Border { get; set; } #

Gets or sets the border for the image.

public String BorderRadius { get; set; } #

Gets or sets the border radius for the image.

public virtual RoundingMode RoundingMode { get; set; } #

Controls how rounding is applied when no explicit radius is set.

public String LinkUrl { get; set; } #

Gets or sets whether the image should be a link.

public Boolean OpenInNewWindow { get; set; } #

Gets or sets whether the image should open in a new window.

public Boolean EmbedAsBase64 { get; set; } #

Gets or sets whether the image should be embedded as base64.

public String Base64Data { get; set; } #

Gets or sets the base64 encoded image data.

public String MimeType { get; set; } #

Gets or sets the image MIME type for embedded images.

public Int32 MaxWidth { get; set; } #

Gets or sets the maximum width for image optimization (in pixels).

public Int32 MaxHeight { get; set; } #

Gets or sets the maximum height for image optimization (in pixels).

public Int32 Quality { get; set; } #

Gets or sets the quality for JPEG compression (0-100).

public Boolean OptimizeImage { get; set; } #

Gets or sets whether to enable automatic image optimization.

public Boolean SkipAutoEmbedding { get; set; } #

Gets or sets whether to skip automatic embedding for this specific image.

public Boolean ForceEmbedding { get; set; } #

Gets or sets whether to force embedding for this specific image.

public String DarkModeSource { get; set; } #

Gets or sets the dark mode image source URL.

public String DarkModeAlternativeText { get; set; } #

Gets or sets the dark mode alternative text.

public Boolean DarkModeEmbedAsBase64 { get; set; } #

Gets or sets whether dark mode image should be embedded as base64.

public String DarkModeBase64Data { get; set; } #

Gets or sets the dark mode base64 encoded image data.

public String DarkModeMimeType { get; set; } #

Gets or sets the dark mode image MIME type.

public Boolean EnableDarkModeSwapping { get; set; } #

Gets or sets whether to enable automatic dark mode image swapping.

Fields

_originalSource #

Stores the original source path before any embedding occurs.

_originalDarkModeSource #

Stores the original dark-mode source path before any embedding occurs.