URL Plugin

The @jsx-email/plugin-url package provides a plugin for modifying URLs in rendered email HTML. The initial append option appends URL parameters to matching URL attributes.

This plugin is not loaded automatically by jsx-email. Add it to your configuration’s plugins array.

Browse this plugin’s source code

Usage

import { defineConfig } from 'jsx-email/config';
import { urlPlugin } from '@jsx-email/plugin-url';

export const config = defineConfig({
  plugins: [
    urlPlugin({
      append: {
        parameters: {
          utm_campaign: 'Campaign Name',
          utm_medium: 'email',
          utm_source: 'jsx-email'
        }
      }
    })
  ]
});

Given this HTML:

<a href="https://example.com">Test</a>

The output will include appended URL parameters:

<a href="https://example.com?utm_campaign=Campaign Name&utm_medium=email&utm_source=jsx-email"
  >Test</a
>

Options

append

Type: Object

Appends URL parameters to matching URL attributes.

attributes

Type: String[] Default: ['src', 'href', 'poster', 'srcset', 'background']

Array of attributes to process for matching tags.

urlPlugin({
  append: {
    attributes: ['data-href', 'src'],
    parameters: {
      foo: 'bar'
    },
    tags: ['a', 'img']
  }
});

parameters

Type: Object

Object containing the URL parameters to append.

urlPlugin({
  append: {
    parameters: {
      custom_parameter: 'foo',
      utm_campaign: 'Campaign Name',
      utm_medium: 'email',
      utm_source: 'jsx-email'
    }
  }
});

qs

Type: Object Default: { encode: false }

Options for serializing appended URL parameters.

urlPlugin({
  append: {
    parameters: {
      foo: '@Bar@'
    },
    qs: {
      encode: true
    }
  }
});

strict

Type: Boolean Default: true

When enabled, URL parameters are appended only to valid URLs. Disable strict mode to append URL parameters to any string.

urlPlugin({
  append: {
    parameters: {
      foo: 'bar'
    },
    strict: false
  }
});