Image & File Handling

HubSpot assets frequently contain images — hero banners in landing pages, logos in email templates, featured images on blog posts, thumbnails in module fields. When you deploy assets to a new portal, these images need to be uploaded to the target portal’s file manager and every URL reference needs to be updated. JetStack AI handles this automatically.

How Image Handling Works

Image handling spans both the import and deploy phases:

1. During import — Images referenced in assets are downloaded and cached in Firebase Storage. The original URLs are recorded alongside each cached file.
2. During deployment — Cached images are uploaded to the target portal via HubSpot’s File Manager API. The new URLs returned by HubSpot replace every occurrence of the original URL in deployed content.

This two-phase approach means images are captured once during import and can be deployed to any number of target portals without re-downloading from the source.

What Gets Cached During Import

When you import assets, JetStack AI scans the asset content for image references and caches them. The types of references detected include:

• HTML img tags — <img src="..."> in page content, email bodies, and rich text fields
• CSS background images — background-image: url(...) in inline styles and stylesheets
• Featured images — Blog post and page featured image URLs
• Module fields — Image picker fields in custom modules and page sections
• Widget images — Images embedded in HubSpot widget configurations

Each detected image URL is downloaded and stored in JetStack AI’s Firebase Storage with a reference back to the original URL. The import process does not modify the original asset data — it only builds a URL-to-cached-file mapping for later use.

Upload During Deployment

When the deploy engine processes an asset, it checks every URL in the asset’s content against the cached image map. For each match:

1. The cached file is retrieved from Firebase Storage
2. A request is made to the HubSpot File Manager API to upload the file to the target portal
3. HubSpot returns a new URL for the uploaded file (hosted on the target portal’s CDN)
4. The original URL is replaced with the new URL in the asset content

This replacement happens before the asset is created via the HubSpot API, so the asset is deployed with correct, portal-local image URLs from the start.

Upload Location

Files are uploaded to the target portal’s file manager under a JetStack AI-specific folder structure. This keeps deployed images organized and easily identifiable.

URL Remapping

The URL replacement engine scans all text content in an asset for occurrences of cached image URLs. This includes:

Content Location	Examples
Page HTML	Body content, header/footer HTML, custom HTML modules
Email bodies	HTML content in marketing emails, drag-and-drop module content
Blog post content	Post body, featured image field, meta image
Module field values	Image picker fields, rich text fields, URL fields
Template source	Image references in template HTML and HubL
HubDB cell values	Image URLs stored in HubDB table cells
CSS content	Inline and embedded background-image references

The replacement is a straightforward string substitution — every occurrence of the original URL is replaced with the new target URL. This handles cases where the same image appears multiple times in a single asset.

Supported File Types

JetStack AI caches and uploads the following file types:

• Images — JPEG, PNG, GIF, SVG, WebP, ICO
• Documents — PDF files referenced in download links or CTA modules

Video files hosted on HubSpot’s video platform are not included in image handling. Video references use HubSpot’s internal video IDs, which are handled by the standard ID remapping engine.

What Happens When Upload Fails

Image upload can fail for several reasons:

• File too large — The file exceeds HubSpot’s file size limit for the target portal’s plan
• API error — Temporary HubSpot API issues during upload
• Invalid file — The cached file is corrupted or in an unsupported format

When an upload fails:

1. The original URL is kept in the asset content. The image will still load if the original source portal’s CDN is accessible.
2. A warning is logged in the deployment activity detail, specifying which file failed and why.
3. The rest of the deployment continues normally — a single failed image does not block the entire deployment.

This means deployed assets may contain a mix of new target-portal URLs (for successfully uploaded images) and original source-portal URLs (for failed uploads). The warnings in the activity log help you identify which images need manual attention.

Edge Cases

Duplicate Images

If the same image URL appears across multiple assets in a single deployment, JetStack AI uploads it once and reuses the target URL for all occurrences. This avoids duplicate files in the target portal’s file manager.

External Images

Images hosted outside of HubSpot (e.g., on a third-party CDN or a company website) are not cached during import and not processed during deployment. These URLs pass through unchanged, which is typically the desired behavior — external images are not portal-specific.

Already-Existing Images

If the target portal already has a file with the same name in the same path, HubSpot’s File Manager API handles this by creating a new version or appending a suffix. JetStack AI uses whatever URL HubSpot returns, so the deployed asset will reference the correct file regardless of naming conflicts.

Image References in Encoded Content

Some HubSpot assets store image URLs in JSON-encoded or HTML-encoded strings. The URL replacement engine handles common encoding patterns:

• URL-encoded strings (%2F instead of /)
• JSON-escaped strings (\/ instead of /)
• HTML entity-encoded URLs

Best Practices

• Check the activity log after deployment. Review any image upload warnings to identify files that need manual upload.
• Verify image-heavy pages. After deploying landing pages or emails with many images, preview them in the target portal to confirm all images render correctly.
• Mind file size limits. If your source portal is on a higher HubSpot plan than the target, some large files may exceed the target’s upload limits.
• Re-deploy if needed. If image uploads fail due to temporary API issues, you can re-run the deployment. The duplicate detection will skip already-created assets, and the image upload will retry for previously failed files.