Generate and troubleshoot Wistia email embeds
Wistia videos can't play inside an email — email clients strip out video players and scripts. Instead, a Wistia email embed is a clickable thumbnail: a poster image with a play button that links to a page where the video actually plays. This guide shows how to generate that embed code programmatically with oEmbed, how each email provider's code differs, and how to troubleshoot the most common surprise (a thumbnail that opens a small, autoplaying media page).
Generate email-friendly Wistia embed codes with oEmbed, and understand what each provider's code does.
What the in-app Email tab produces
When you open a video's embed options in Wistia and choose Email, Wistia generates a clickable thumbnail. The recipient sees a poster image with a play button; clicking it opens the video on a Wistia page (your public media URL). The HTML is a single <a href="..."> wrapping an <img> — no <script>, no player — so it survives email clients.
That same output is available programmatically through our oEmbed endpoint, so you can build your own UI or generate codes in bulk without clicking through the app.
Generating an email embed with oEmbed
Wistia's oEmbed endpoint (https://fast.wistia.com/oembed) returns an email embed when you add embedType=email to the media URL you pass in. Add emailProvider to get a code tailored to your email platform.
New to oEmbed?See Wistia and oEmbed for the endpoint basics, accepted URL formats, and response shape. This page covers the email-specific parameters only.
Request
curl "https://fast.wistia.com/oembed?url=https%3A%2F%2Fyour-subdomain.wistia.com%2Fmedias%2Fe4a27b971d%3FembedType%3Demail%26emailProvider%3Dhub_spot"You can pass the email options (embedType, emailProvider, and any others below) two ways — pick whichever is easier:
- In the
urlparameter's own query string (shown above). URL-encode the whole media URL when you do this. - As top-level query params on
/oembed, alongsideurl. For example:
curl "https://fast.wistia.com/oembed?url=https%3A%2F%2Fyour-subdomain.wistia.com%2Fmedias%2Fe4a27b971d&embedType=email&emailProvider=hub_spot"Both produce the same result, because the endpoint merges the nested and top-level params. The top-level form avoids double-encoding, so it's usually simpler.
Response
{
"version": "1.0",
"type": "video",
"html": "<a href=\"http://your-subdomain.wistia.com/medias/e4a27b971d?wemail={{contact.email}}\"><img src=\"https://embed-ssl.wistia.com/deliveries/....jpg?...&image_play_button_color=174bd2e0\" alt=\"Your video\" width=\"450\" height=\"253\" /></a>",
"thumbnail_url": "https://embed-ssl.wistia.com/deliveries/....jpg",
"title": "Your video",
"duration": 16.51
}The html field is the email embed code. Drop it into your campaign.
Email provider parameter
Pass emailProvider to get a code formatted for your platform. The differences are real and matter:
- Mailchimp returns a Mailchimp merge-tag block (
*|WISTIA:[...]|*), not raw HTML. Mailchimp expands it into the thumbnail at send time. - Constant Contact returns an
<a>withtrack="off" linktype="link"so Constant Contact doesn't rewrite the link. - Every other provider returns a clickable-thumbnail
<a><img></a>, with the recipient's email address merged into the watch-page link via that provider's merge-tag syntax.
emailProvider value | Platform | Email merge tag used | ||
|---|---|---|---|---|
mail_chimp | Mailchimp | `* | *` (merge-tag block) | |
constant_contact | Constant Contact | [[emailAddress]] | ||
hub_spot | HubSpot | {{contact.email}} | ||
marketo | Marketo | {{lead.Email Address:default=noemail}} | ||
pardot | Pardot | {{Recipient.Email}} | ||
klaviyo | Klaviyo | {{ email }} | ||
campaign_monitor | Campaign Monitor | [email] | ||
drip | Drip | {{ subscriber.email }} | ||
convert_kit | ConvertKit | {{ subscriber.email_address }} | ||
active_campaign | ActiveCampaign | %EMAIL% | ||
get_response | GetResponse | [[email]] | ||
a_weber | AWeber | {!email} | ||
i_contact | iContact | [email] | ||
infusionsoft | Keap (Infusionsoft) | ~Contact.Email~ | ||
ontraport | Ontraport | [Email] | ||
emma | Emma | [[email]] | ||
email_contact | EmailContact | [%email%] | ||
vertical_response | VerticalResponse | {EMAIL_ADDRESS} | ||
mad_mimi | Mad Mimi | (email) | ||
dotmailer | dotdigital (dotmailer) | @email@ | ||
sendible | Sendible | $email | ||
lyris | Lyris | %%emailaddr%% | ||
what_counts | WhatCounts | [~email~] | ||
blue_hornet | BlueHornet | [%%to_email%%] | ||
emailvision | EmailVision | [EMV FIELD]EMAIL[EMV /FIELD] | ||
accrisoft | Accrisoft | [[email]] | ||
none | Generic / no platform | (no merge tag) |
If you omit emailProvider or pass none, you get a plain clickable thumbnail linking to the watch page with no email merge tag.
Why the email merge tag?The recipient's address is appended to the watch-page link as
wemail=.... When the viewer clicks through and watches, Wistia ties that play to their email address, so the engagement shows up against the right contact in your analytics.
Optional parameters
Add these to the url query string alongside embedType=email:
| Parameter | Effect |
|---|---|
thumbnailWidth | Thumbnail width in pixels (default 450). Height is derived from the video's aspect ratio unless you also set thumbnailHeight. |
thumbnailHeight | Thumbnail height in pixels. |
playerColor | Hex color (no #) for the play button. |
playButton | false to remove the play-button overlay from the thumbnail. |
linkUrl | Override the click-through destination (defaults to the public media URL). |
autoPlay | true appends wvideo=<hashed_id> to the watch-page link so the video starts playing on arrival. See the troubleshooting note below before using this. |
Troubleshooting
The thumbnail opens a small page that starts autoplaying
This is the single most common email-embed surprise, and it's caused by autoPlay=true.
An email thumbnail always links out to a Wistia page — the video can't play in the inbox. When autoPlay=true is set, Wistia adds wvideo=<hashed_id> to that link, which tells the destination page to start the video automatically. Depending on where the link points (and the recipient's browser), that can look like a bare, small media page that begins playing on its own rather than a polished landing experience.
Fixes:
- Drop
autoPlay(or set it tofalse) if you don't want auto-start. The recipient lands on the page and clicks play themselves. - Point the click-through at a real landing page with
linkUrl=...— e.g. a page on your site that has a normal Wistia embed on it — instead of the bare public media URL. The thumbnail in the email is just an image link; it can go anywhere.
Mailchimp shows *|WISTIA:[...]|* literally instead of a thumbnail
*|WISTIA:[...]|* literally instead of a thumbnailThe Mailchimp code is a merge-tag block, not HTML — Mailchimp expands it at send time. It looks like raw text in a code view but renders as a thumbnail in the actual campaign. Send yourself a test to confirm. If it still shows literally, make sure you pasted it into a content block that allows Mailchimp merge tags (not a raw-HTML block that escapes them).
The link isn't tracking which contact watched
Make sure you passed the correct emailProvider so the right merge tag (wemail=...) is in the link, and that your platform actually substitutes that merge tag at send time (some require the field to be populated on the contact record).