Newsletter Subscription

Collect email subscribers directly from your website with beautiful, ready-to-use UI components or a simple programmatic API.

Installation

The newsletter module is included in inline.js. No additional scripts needed — it's available automatically when you load the Cuoral widget:

<script
  src="https://js.cuoral.com/inline.js"
  data-cuoral-key="your-public-key"
></script>

The CuoralNewsletter object is then globally available.

Method 1: Modal Popup

Show a beautiful animated modal to collect subscriptions. Great for exit-intent, button clicks, or timed popups.

CuoralNewsletter.showModal({
  title: "Stay in the loop",
  subtitle: "Get the latest updates delivered to your inbox.",
  buttonText: "Subscribe",
  color: "#6366f1",
  showName: true,
  showConsent: true,
  consentText: "I agree to receive emails and can unsubscribe anytime.",
  successTitle: "You're subscribed! 🎉",
  successMessage: "Check your inbox for confirmation.",
  tags: ["website-popup"],
  onSuccess: (data) => {
    console.log("Subscribed!", data);
  },
  onError: (error) => {
    console.error("Failed:", error);
  },
  onClose: () => {
    console.log("Modal closed");
  },
});

Modal Options

Parameter	Type	Default	Description
title	string	"Stay in the loop"	Modal heading
subtitle	string	"Get the latest updates..."	Description text
buttonText	string	"Subscribe"	Submit button label
color	string	"#6366f1"	Brand/theme color (hex)
showName	boolean	false	Show first & last name fields
showConsent	boolean	true	Show consent checkbox
consentText	string	"I agree to receive..."	Custom consent label
successTitle	string	"You're subscribed! 🎉"	Title after success
successMessage	string	"Thanks for subscribing..."	Message after success
tags	string[]	[]	Tags for subscriber segmentation
onSuccess	function	null	Callback with subscriber data
onError	function	null	Callback with error details
onClose	function	null	Callback when modal is closed

Method 2: Inline Form Embed

Embed a form directly into any element on your page. Perfect for footers, sidebars, or dedicated signup sections.

CuoralNewsletter.embed("#newsletter-container", {
  title: "Subscribe to our newsletter",
  subtitle: "Stay updated with the latest news.",
  layout: "inline",
  color: "#6366f1",
  buttonText: "Subscribe",
  showName: false,
  tags: ["footer-form"],
  onSuccess: (data) => console.log("Subscribed!", data),
  onError: (error) => console.error("Error:", error),
});

Embed Options

Parameter	Type	Default	Description
target (1st arg)	string | Element	—	CSS selector or DOM element
title	string	"Subscribe to our newsletter"	Form heading
subtitle	string	"Stay updated..."	Description text
buttonText	string	"Subscribe"	Submit button label
color	string	"#6366f1"	Brand/theme color (hex)
showName	boolean	false	Show first & last name fields
layout	string	"stacked"	"stacked" or "inline"
tags	string[]	[]	Tags for subscriber segmentation
onSuccess	function	null	Callback with subscriber data
onError	function	null	Callback with error details

Layout Options

• "inline" — Email input and button on the same row (compact, great for headers/footers)

• "stacked" — Fields stacked vertically (traditional form layout)

Note: Inline layout only works when showName is false. If name fields are enabled, it falls back to stacked.

Method 3: Programmatic Subscribe

For custom forms where you handle the UI yourself. Just pass the email and get the result.

// Inside your own form submit handler
const result = await CuoralNewsletter.subscribe({
  email: "[e-mail]",
  firstName: "John",        // optional
  lastName: "Doe",          // optional
  tags: ["custom-form"],    // optional
  customFields: {           // optional
    company: "Acme Inc",
    role: "Developer",
  },
});

if (result.status) {
  // Success!
  console.log(result.data);
  // { email: "[e-mail]", contact_uid: "...", is_subscribed: true }
} else {
  // Error
  console.error(result.message);
}

Subscribe Options

Parameter	Type	Required	Description
email	string	✅ Yes	Subscriber's email address
firstName	string	No	First name
lastName	string	No	Last name
tags	string[]	No	Tags for segmentation
customFields	object	No	Custom key-value metadata

Response Format

{
  "status": true,
  "message": "Successfully subscribed",
  "data": {
    "email": "[e-mail]",
    "contact_uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "is_subscribed": true,
    "subscription_state": "active",
    "requires_confirmation": false
  }
}

Examples

Trigger modal on button click

<button onclick="CuoralNewsletter.showModal({ color: '#e11d48' })">
  Subscribe Now
</button>

Embed in footer

<div id="footer-newsletter"></div>
<script>
  CuoralNewsletter.embed("#footer-newsletter", {
    layout: "inline",
    title: "",
    subtitle: "",
    buttonText: "→",
    color: "#1e293b",
  });
</script>

Exit-intent popup

let shown = false;
document.addEventListener("mouseout", (e) => {
  if (e.clientY < 10 && !shown) {
    shown = true;
    CuoralNewsletter.showModal({
      title: "Wait! Don't leave yet 👋",
      subtitle: "Subscribe for a 10% discount on your first purchase.",
      color: "#059669",
      tags: ["exit-intent"],
    });
  }
});

Custom form integration

<form id="my-form">
  <input type="email" id="my-email" placeholder="Enter email" />
  <button type="submit">Subscribe</button>
</form>

<script>
document.getElementById("my-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  const email = document.getElementById("my-email").value;

  const result = await CuoralNewsletter.subscribe({ email });

  if (result.status) {
    alert("Subscribed successfully!");
  } else {
    alert("Error: " + result.message);
  }
});
</script>

Notes

• org_identifier is automatically set from your data-cuoral-key attribute.

• source_details auto-captures the current page URL where the subscription happened.

• consent is auto-generated with a timestamp when the user subscribes.

• The modal auto-closes 4 seconds after successful subscription.

• All forms include built-in email validation.

• Responsive design works on all screen sizes.

• Demo URL: https://js.cuoral.com/newsletter-demo.html