> For the complete documentation index, see [llms.txt](https://contacted.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://contacted.gitbook.io/docs/playground/images.md).

# Images

## Working with Images

Images bring your emails to life and significantly improve engagement rates. Contacted makes it incredibly simple to include content images in your transactional emails—just pass image URLs in your data and reference them in your prompts.

> **Note:** Your company branding (logos, footers, headers) is already configured in your account settings and applied automatically. This guide focuses on content-specific images like product photos, charts, and promotional banners.

### How Images Work

**1. Pass content image URLs in your `data` object**\
**2. Reference the image keys in your `prompt` with specific placement instructions**\
**3. Our AI handles sizing, positioning, and responsive design automatically**\
**4. Your pre-configured branding wraps around the content seamlessly**

> **Important:** All image values must be provided as URL strings. Our AI automatically optimizes images for email clients.

***

### Basic Image Usage

#### Simple Example

```python
contacted.send(
    subject="Welcome to Our Platform!",
    prompt="Welcome email with welcome_banner as a hero image showcasing our platform",
    data={
        "user_name": "Sarah Johnson",
        "welcome_banner": "https://yoursite.com/images/welcome-hero.jpg"
    }
)
```

#### What Happens:

* Your branded header/logo appears automatically (from account settings)
* `welcome_banner` becomes a prominent hero image in the email body
* Your branded footer appears automatically
* AI handles responsive sizing and email client compatibility

***

### Content Image Types & Use Cases

#### 1. **Hero/Banner Images**

**Use for:** Main visual content, announcements, featured content

```python
data={
    "hero_image": "https://yoursite.com/sale-banner.jpg",
    "announcement_banner": "https://yoursite.com/new-feature.png"
}

prompt="Product announcement with hero_image as the main banner showcasing the new feature"
```

#### 2. **Product Images**

**Use for:** Product showcases, order confirmations, catalogs

```python
data={
    "product_image": "https://store.com/products/premium-headphones.jpg",
    "product_gallery": "https://store.com/gallery/headphones-lifestyle.jpg"
}

prompt="Order confirmation showing product_image prominently with order details below"
```

#### 3. **Data Visualization Images**

**Use for:** Charts, graphs, reports, analytics

```python
data={
    "monthly_chart": "https://analytics.com/charts/may-2025.png",
    "performance_graph": "https://reports.com/graphs/q2-performance.jpg"
}

prompt="Monthly report email with monthly_chart showing growth metrics and performance_graph in the detailed analysis section"
```

#### 4. **Content & Marketing Images**

**Use for:** Event promotions, marketing campaigns, feature highlights

```python
data={
    "event_banner": "https://events.com/devcon-2025-banner.jpg",
    "feature_screenshot": "https://app.com/screenshots/new-dashboard.png",
    "promotional_image": "https://marketing.com/summer-sale-2025.jpg"
}

prompt="Event invitation with event_banner as header and feature_screenshot showing the new capabilities"
```

#### 5. **Personal & Team Images**

**Use for:** User-specific content, team introductions, personal touches

```python
data={
    "user_avatar": "https://profiles.com/users/sarah-j.jpg",
    "team_photo": "https://company.com/team/support-team.jpg"
}

prompt="Support ticket response with user_avatar next to greeting and team_photo introducing our support team"
```

***

### Advanced Content Image Placement

#### Multiple Content Images with Specific Instructions

```python
contacted.send(
    subject="Your Q2 Business Report",
    prompt="""
    Quarterly business report email structure:
    
    1. Place report_cover as a large hero image after the greeting
    2. Insert revenue_chart in the financial metrics section  
    3. Add team_photo in the "Meet Your Account Team" section
    4. Include comparison_infographic showing market position
    
    Make the report_cover and revenue_chart prominent and readable.
    Keep team_photo smaller and professional.
    """,
    data={
        "customer_name": "Acme Corporation",
        "quarter": "Q2 2025",
        "report_cover": "https://reports.com/q2-2025-cover.jpg",
        "revenue_chart": "https://analytics.com/charts/q2-revenue.png",
        "team_photo": "https://team.com/account-managers.jpg",
        "comparison_infographic": "https://charts.com/market-position.png",
        "revenue_growth": "23%",
        "key_wins": "Expanded to 3 new markets, launched premium tier"
    }
)
```

#### Product Showcase with Multiple Images

```python
contacted.send(
    subject="Your Order Ships Tomorrow!",
    prompt="""
    Shipping notification with product showcase:
    
    - Place main_product as the hero showcasing the primary item
    - Create a gallery section with accessory_1, accessory_2 showing included accessories
    - Add unboxing_preview showing what the package will look like
    - Include care_instructions as a helpful infographic
    """,
    data={
        "customer_name": "Jordan Kim",
        "order_number": "ORD-7892",
        "main_product": "https://products.com/gaming-laptop-hero.jpg",
        "accessory_1": "https://products.com/wireless-mouse.jpg",
        "accessory_2": "https://products.com/laptop-stand.jpg", 
        "unboxing_preview": "https://packaging.com/premium-unboxing.jpg",
        "care_instructions": "https://guides.com/laptop-care-infographic.png",
        "tracking_number": "TK123456789",
        "estimated_delivery": "June 18, 2025"
    }
)
```

***

### Overriding Branding (Advanced)

While your branding is applied automatically, you can override specific elements when needed:

#### Custom Header for Special Campaigns

```python
contacted.send(
    subject="Black Friday Mega Sale!",
    prompt="""
    Special Black Friday email. Override the standard header with sale_header 
    showing our Black Friday branding. Use deal_banner as main hero image.
    Include countdown_timer showing time remaining.
    """,
    data={
        "sale_header": "https://campaigns.com/black-friday-header.png",
        "deal_banner": "https://campaigns.com/mega-sale-hero.jpg", 
        "countdown_timer": "https://timers.com/black-friday-countdown.gif",
        "sale_percentage": "70%",
        "sale_end_date": "November 29, 2025"
    }
)
```

#### Event-Specific Branding

```python
contacted.send(
    subject="DevCon 2025 Registration Confirmed",
    prompt="""
    Conference confirmation email. Use event_header instead of standard 
    company header to show conference branding. Include confirmation_banner
    and venue_photo for event atmosphere.
    """,
    data={
        "event_header": "https://devcon.com/email-headers/devcon-2025.png",
        "confirmation_banner": "https://devcon.com/confirmations/registered.jpg",
        "venue_photo": "https://venues.com/sf-convention-center-interior.jpg",
        "attendee_name": "Alex Rivera",
        "ticket_type": "Full Conference Pass"
    }
)
```

***

### Best Practices

#### ✅ Content Image Requirements

**Supported Formats:** JPG, PNG, GIF, WebP\
**Recommended Size:** 600-1200px wide for hero images, 300-600px for secondary content\
**Max File Size:** 5MB per image\
**Hosting:** Use reliable CDNs or image hosting services

```python
# ✅ Good Content URLs
"hero_banner": "https://cdn.yoursite.com/banners/welcome.jpg"
"product_shot": "https://cdn.shopify.com/products/item-123.jpg"
"chart_image": "https://analytics.yourapp.com/charts/monthly.png"

# ❌ Avoid
"bad_image": "http://localhost:3000/image.png"  # Not accessible
"broken_link": "https://site.com/missing.jpg"   # Broken links
"too_large": "https://site.com/huge-20mb.png"   # Too large
```

#### 🎯 Prompt Best Practices

**Be Specific About Content Placement:**

```python
# ✅ Specific placement for content
prompt="Welcome email with hero_banner as main showcase image and product_grid showing our popular items"

# ❌ Vague placement  
prompt="Welcome email with some images"
```

**Describe Content Purpose:**

```python
# ✅ Purpose-driven
prompt="Newsletter with feature_screenshot showing the new dashboard and tutorial_gif demonstrating key features"

# ❌ No context
prompt="Newsletter with screenshot and gif"
```

**Focus on Content Layout:**

```python
# ✅ Content-focused layout
prompt="Invoice with product_images in itemized section and shipping_infographic showing delivery timeline"

# ❌ No layout guidance
prompt="Invoice with product images and shipping info"
```

***

### Common Content Use Cases

#### E-commerce Product Showcase

```python
contacted.send(
    subject="New Arrivals Just For You!",
    prompt="""
    Product showcase email:
    - Use collection_hero as main banner showcasing new arrivals
    - Display featured_product_1, featured_product_2, featured_product_3 in a grid
    - Include styling_tips as a lifestyle infographic
    """,
    data={
        "customer_name": "Maya Patel",
        "collection_name": "Summer Essentials",
        "collection_hero": "https://store.com/collections/summer-hero.jpg",
        "featured_product_1": "https://products.com/summer-dress-blue.jpg",
        "featured_product_2": "https://products.com/sandals-tan.jpg",
        "featured_product_3": "https://products.com/sun-hat-white.jpg",
        "styling_tips": "https://guides.com/summer-styling-tips.png",
        "sale_percentage": "25%",
        "shop_url": "https://store.com/collections/summer"
    }
)
```

#### SaaS Feature Announcement

```python
contacted.send(
    subject="New Feature: Advanced Analytics Dashboard",
    prompt="""
    Feature announcement email:
    - Place feature_hero as main announcement banner
    - Insert dashboard_screenshot showing the new interface
    - Add before_after showing the improvement
    - Include tutorial_preview for getting started
    """,
    data={
        "user_name": "Chris Wong",
        "feature_name": "Advanced Analytics Dashboard", 
        "feature_hero": "https://announcements.com/analytics-hero.jpg",
        "dashboard_screenshot": "https://screenshots.com/new-dashboard.png",
        "before_after": "https://comparisons.com/old-vs-new-analytics.jpg",
        "tutorial_preview": "https://tutorials.com/analytics-preview.gif",
        "beta_access_link": "https://app.com/beta/analytics"
    }
)
```

***

### Troubleshooting Content Images

#### Common Issues

**Issue:** Content images not displaying

```
Solution: Verify URLs are publicly accessible and use HTTPS
Test: Open image URL directly in browser
```

**Issue:** Content images too large/small in email body

```
Solution: Be more specific about sizing in prompts
Example: "large hero_banner" vs "small thumbnail_image"
```

**Issue:** Content images in wrong position

```
Solution: Provide clearer content layout instructions
Example: "main_product prominently at top" vs "main_product in the content area"
```

**Issue:** Content images clashing with brand elements

```
Solution: Ensure content images complement your brand colors
Tip: Preview in playground to see final result with branding
```

***

### Advanced Content Techniques

#### Dynamic Content Generation

Use dynamic URLs for personalized content:

```python
data={
    "user_chart": f"https://charts.yourapp.com/user/{user_id}/monthly.png",
    "personal_report": f"https://reports.yourapp.com/user/{user_id}/summary.jpg",
    "custom_product": f"https://products.yourapp.com/recommended/{user_id}.jpg"
}
```

#### A/B Testing Content Images

Test different content approaches:

```python
# Version A - Product focus
hero_image = "https://site.com/product-hero-a.jpg"

# Version B - Lifestyle focus  
hero_image = "https://site.com/lifestyle-hero-b.jpg"

contacted.send(
    prompt=f"Welcome email with hero_image showcasing our premium experience",
    data={"hero_image": hero_image}
)
```

#### Seasonal Content Swapping

Automatically use seasonal content:

```python
import datetime

season = "summer" if datetime.now().month in [6,7,8] else "winter"
seasonal_content = f"https://content.com/{season}-promotion.jpg"

data={
    "seasonal_banner": seasonal_content,
    "seasonal_products": f"https://products.com/{season}-collection.jpg"
}
```

***

### Summary

Content images in Contacted emails are powerful but simple:

1. **Your branding is handled automatically** from account settings
2. **Pass content image URLs as strings in your `data` object**
3. **Reference image keys in your `prompt` with specific instructions**
4. **Focus on content placement and purpose, not branding elements**
5. **Use reliable, fast-loading image hosting for content**
6. **Override branding only when needed for special campaigns**

Our AI handles all the technical complexity—responsive design, email client compatibility, and optimal sizing—while seamlessly integrating your content with your pre-configured brand identity.

Ready to create visually stunning emails? Start with simple hero banners and work your way up to complex content showcases!