oEmbed is a standardized format for allowing content to be embedded on a website. The end-user’s (consumer) browser sends a GET request to a provider's API endpoint with the following parameters.
- URL (required)
- maxWidth (optional)
- maxHeight (optional)
- format (optional)
The provider then returns structured data in the specified format. This data is then used to display the embedded content on the end-users (consumers) page. For more information on oEmbed, please refer to the official documentation for the oEmbed specification.
We offer two video embed modules (email and pages), one Embed field (Media URL) for custom modules, and one function (email only) that makes use of oEmbed for helping to implement embedded content on your website.
Inside of our modules, you will see a "Media URL" field. This field is equal to the "URL" parameter as mentioned above in the oEmbed specification. Our modules do all the heavy lifting of requesting the information, known as the oEmbed Response, from the URL you specify here and making it available on your site.
When using the
oembed() function inside of email, you simply provide a request string that includes the URL, Max Width, and Max Height. You can see an example of this function on our developer documentation.
An oEmbed Response is JSON data that is returned by a provider (such as YouTube, Flickr, or any others that support oEmbed) which contains various information that is related to the item being fetched. You can view the response parameters on the oEmbed documentation under Section 2.3.4. Each response type (photo, video, link, and rich) has specific parameters that are associated with them.
An example of an oEmbed Response from YouTube is below. If you look closely, you will see that the video type provides an HTML parameter that returns the code you would want to use when embedding the video player on your website.
If your module is being used strictly for email and you’re looking to make use of the embed field, we recommend using the embed field in conjunction with the
oembed() function. Below is an example of this in use:
This function returns a dictionary containing the parameters of the oEmbed response for the specified url. Individual parameters can be accessed using dot notation.
Below is an example of this using a YouTube video as a media url source.
If your module is being used for email in conjunction with page and/or blog, you also have the ability to use the
oembed_response object. Once the url is entered in the Media URL field and pulled this data is then cached on our end for use with an
oembed_response object. Below is a sample of how you can view the
You can use dot notation to then grab child elements from the dict. For example when using a YouTube video as a source you can do the following:
In order to update the data in the cached
oembed_response, you would have to modify your media URL (remove a letter and re-add) and re-apply the changes to your module.
When adding "Media URL" links into your video embed module or embed field, you may run into an error that states
"You can’t embed this media URL for sharing.”
When you receive this error, there are a few things you will want to check with the provider.
- Does the Asset provider have oEmbed functionality in their platform? The oEmbed official documentation contains a list of providers that support this specification. You may also want to reach out to your provider directly to see if they support this as well.
- Is the URL "Private"? Many platforms allow users to hide their content from being viewed publicly. For example, if you have an Instagram account that is private, you may not be able to embed content from your posts if it is not available publicly (without requiring the user to sign in to the platform or be a follower/friend).
The following are status codes that are defined as per the oEmbed Specification:
- 404 Not Found: There is no response found for the requested URL.
- 501 Not Implemented: The requested response format cannot be returned.
- 401 Unauthorized: The requested URL contains a private (non-public) resource.
HubSpot does not have direct control over how third-party providers implement their status codes or how they align to the oEmbed Specification. Because of this, we return either a 404 where applicable or a 400 status code and similar messaging to what you see above. The messaging is contained inside of the response object in the
Thank you for your feedback, it means a lot to us.