Media source plugin configuration
Setting up your media source plugins
Kit’s media source plugin lets you extend our email editor to allow creators to natively add images from external sources into their content. This guide walks you through configuring your plugin’s appearance, behavior, and settings—from naming and visual presentation to backend functionality and user controls.
Name
The plugin name
is the user-facing name for your block and will be shown in the content block menu and in the media gallery itself. In the example above, the plugin name
is “Your plugin name”. Your name should be short, ideally one or two words.
Description
The description
is a short phrase describing your media source. It will appear underneath the name in the content block menu. In the example above this is set to “Short description for the plugin”.
Sort order
If you have multiple media sources within the same app, the sort order
determines their placement within both the media gallery and the content block menu. In the images above, “Your plugin name” has a sort order
of 0, while “Your plugin name 2” has a sort order
of 1.
Logo
The logo
is an image for the element to be displayed alongside the name
and the description
. Only PNG, GIF, JPEG extensions are supported. The recommended size is 150x120px.
Request URL
The request URL
is the URL of an endpoint on your server that returns the list of images, complete with all the necessary properties to render the images in the gallery and place them within the email content for use by the creator.
You’ll generate this response based on the settings you’ve defined for your media source (outlined in the next section). Once a user completes all required settings, we’ll make a POST request to your request URL
.
The request will contain a settings
object with the user’s selected values for each of your search, filter, and sort settings, as well as pagination details, like so:
Note - your app should also handle the empty case, ensuring you show some media by default when the creator opens up your plugin without interacting with any of the configuration elements your app offers.
If you’ve encountered an error, return an object containing an errors array of strings. You may add as many errors to this array as you’d like.
Settings JSON
The media gallery supports three optional groups that settings can be placed in: search_group
, filter_group
, & sort_group
. Each group currently accepts a single setting that can be used by creators to filter and sort your content for ease of use.
Configuration with a search, filter and sort component could look like so:
Details on the individual configuration options can be found on the plugin settings page.