Skip to content

docs: add inline and external image example #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gregsvo merged 1 commit into from
Jun 3, 2026
Merged

docs: add inline and external image example #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions examples/outbound_messages/send_with_inline_and_external_images.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
"""
Example: combining inline (base64) images and external image URLs in one email.

Use case:
- Inline images (content_id / cid:) are embedded in the email itself.
The recipient's email client displays them without making any external HTTP
request, which is ideal for logos or brand assets you always want visible.
- External image URLs are loaded from a remote server at open time.
This is the standard technique for tracking pixels and analytics because
the server can record who fetched the image and when.

Both techniques can appear in the same html_body.
"""

import asyncio
import base64
import os

import postmark
from postmark.models.outbound import Attachment, Email

try:
from dotenv import load_dotenv

load_dotenv()
except ImportError:
Comment thread
gregsvo marked this conversation as resolved.
Dismissed
pass

SENDER = os.environ["POSTMARK_SENDER_EMAIL"]

# External tracking pixel URL — loaded by the recipient's email client at open
# time, so the server can record the open event.
TRACKING_PIXEL_URL = "https://track.example.com/pixel.png"


async def main():
async with postmark.ServerClient(os.environ["POSTMARK_SERVER_TOKEN"]) as client:
# Inline logo — embedded in the email as base64, no external request.
with open("/path/to/logo.png", "rb") as f:
inline_logo = Attachment(
name="logo.png",
content=base64.b64encode(f.read()).decode("utf-8"),
content_type="image/png",
content_id="cid:logo", # referenced below as <img src="cid:logo">
)

html_body = f"""
<html><body>
<!-- Inline image: served from the email itself, always visible offline -->
<img src="cid:logo" alt="Logo" />

<p>Hello! Thanks for reading.</p>

<!-- External image: fetched at open time for analytics -->
<img src="{TRACKING_PIXEL_URL}" width="1" height="1" alt="" />
</body></html>
"""

response = await client.outbound.send(
Email(
sender=SENDER,
to="receiver@example.com",
subject="Hello — with inline logo and tracking",
text_body="Hello! Thanks for reading. (Open the HTML version to see the logo.)",
html_body=html_body,
attachments=[inline_logo],
)
)

print(f"Sent: {response.message_id}")


asyncio.run(main())