Embed Widget

Put a signup form on your website.

Preview

Embed code

Using the publication ID means your embed won't break if you rename your publication or change your username. Find your publication ID in your publication settings.

Add this where you want the form:

<div
  data-joyful-embed
  data-publication-id="your-publication-id"
></div>
<script src="https://joyful.to/embed/p/your-publication-id/widget.js"></script>

Using username and slug

Alternatively, you can use your username and publication slug. Note that this will break if you rename either.

<div
  data-joyful-embed
  data-username="yourname"
  data-publication="newsletter"
></div>
<script src="https://joyful.to/embed/yourname/newsletter/widget.js"></script>

Custom styling

The widget picks up colors from your publication settings. For more control, override the CSS classes on your site using !important.

Try it

Toggle styles to see how each class affects the widget:

All CSS classes

• .joyful-widget — main container
• .joyful-widget-header — header wrapper
• .joyful-widget-title — title text
• .joyful-widget-description — description text
• .joyful-widget-form — form container
• .joyful-widget-input — email input
• .joyful-widget-button — subscribe button
• .joyful-widget-success — success message
• .joyful-widget-error — error message
• .joyful-widget-privacy — privacy text

Example

.joyful-widget {
  box-shadow: none !important;
  border: 1px solid #e5e5e5 !important;
}

.joyful-widget-button {
  background: #000 !important;
}

.joyful-widget-privacy {
  display: none !important;
}

Direct API

Want full control? Post directly. You can use either username + publication slug, or just the publication ID:

// Using publication ID (recommended - won't break on rename)
fetch('https://joyful.to/api/embed/subscribe/your-publication-id', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'subscriber@example.com' })
})

// Using username + publication slug
fetch('https://joyful.to/api/embed/subscribe/yourname/newsletter', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'subscriber@example.com' })
})

Or use a plain HTML form with a redirect:

<!-- Using publication ID (recommended) -->
<form action="https://joyful.to/api/embed/subscribe/your-publication-id" method="POST">
  <input type="email" name="email" required />
  <input type="hidden" name="redirect" value="https://yoursite.com/thanks" />
  <button type="submit">Subscribe</button>
</form>

<!-- Using username + publication slug -->
<form action="https://joyful.to/api/embed/subscribe/yourname/newsletter" method="POST">
  <input type="email" name="email" required />
  <input type="hidden" name="redirect" value="https://yoursite.com/thanks" />
  <button type="submit">Subscribe</button>
</form>

Auto-tagging subscribers

Tag subscribers automatically when they sign up. Useful for tracking where people came from or segmenting by signup source. Tags are created automatically if they don't exist.

Add tags via URL query parameter:

<form action="https://joyful.to/api/embed/subscribe/yourname/newsletter?tag=homepage" method="POST">
  ...
</form>

Or as a hidden form field:

<input type="hidden" name="tag" value="footer-form" />

Or in your JSON body:

body: JSON.stringify({
  email: 'subscriber@example.com',
  tag: 'api-signup'
})

Multiple tags work too—use multiple ?tag= params or multiple hidden fields.