Embed MailerPress sign-up forms on external websites

Embed Forms lets you place a MailerPress sign-up form on a website other than your WordPress site: a landing page, a static site, a shop on another platform, or any page where you can paste HTML. Visitors who subscribe are added to your MailerPress lists, as with a form on your own site.

This feature requires MailerPress Pro. Without it, MailerPress > Settings > Embed Forms only shows an upgrade notice.

Each external form uses an API key: a secret code, created in MailerPress, that lets the form talk to your site. The key can be restricted to your domains and has its own rate limit (a maximum number of sign-ups per period). The key is visible in the external page’s code, but it can only send sign-ups to MailerPress, not read your contacts.

Create an API key

Go to MailerPress > Settings > Embed Forms.
Click Create New API Key.
Fill in the fields from the table below, then click Generate Key.
A notice shows the new key. Click Copy API Key and store it somewhere safe: the full key is shown only once.
In the same notice, click Generate Embed Code to build the form code with the key already included.

Field	Description
Key Name	Required. A name to recognize the form, for example “Landing Page Form” or “External Website”.
Allowed Domain	Domains allowed to submit the form, without `https://` (for example `example.com`). Separate several domains with commas. Leave empty to allow all domains, but setting a domain is highly recommended.
Maximum Requests	Number of submissions allowed during the time window, from 1 to 1000.
Time Window (minutes)	Length of the time window, from 1 to 60 minutes.
Notes (optional)	Internal notes, for example where the form is used.

Maximum Requests and Time Window (minutes) are pre-filled with your values from MailerPress > Settings > Spam Protection. The limit applies per visitor IP address (the visitor’s internet connection) for this key. See Security & Spam Protection.

Build the form and get the embed code

Design the form in the Generate Embed Code window. The embed code at the bottom updates as you change the options.

Option	Description
Select Lists	Lists the new contact joins.
Select Tags (optional)	Tags (labels to sort contacts) added to the contact.
Standard Fields to Include	Email (required) is always included. Tick First Name and Last Name to show these fields.
Custom Fields (optional)	MailerPress custom fields to show in the form. Each keeps its field type (text, number, date, checkbox or select) and its required setting.
GDPR Consent Checkbox	Adds a consent checkbox (for privacy laws such as the GDPR) that visitors must tick to subscribe.
Labels	Email label, First Name label, Last Name label, Submit button text and GDPR consent text.
Messages	Success message, Error message, Invalid email message, Rate limit message, GDPR required message and Submitting text.
Custom CSS (optional)	Styles to match the external website’s design.

Click Copy Embed Code. The embed code contains a container, a script loaded from your WordPress site, and the form settings. It looks like this (shortened):

HTML

<div id="mailerpress-embed"></div>
<script src="https://your-site.com/wp-content/plugins/mailerpress/build/dist/js/embed-widget.js"></script>
<script>
  new MailerPressEmbed({
    apiKey: 'YOUR_API_KEY_HERE',
    endpoint: 'https://your-site.com/wp-json/mailerpress/v1/embed/contact',
    container: '#mailerpress-embed',
    lists: [1],
    tags: [],
    fields: ["email","firstName"],
    ...
  });
</script>

Paste the full code into the HTML of the external page, where the form should appear. Before you do:

If you open Embed Code later from the key list, the embed code contains YOUR_API_KEY_HERE instead of the key. Replace it with the key you saved at creation.
The two URLs in the embed code use your WordPress site’s address. If WordPress is installed in a subfolder, or if your REST API uses a different address, adjust both URLs.

What happens when a visitor subscribes

MailerPress checks the API key, the allowed domain and the rate limit, then creates or updates the contact with the selected lists, tags and fields.
Double opt-in (the contact confirms by clicking a link in an email) follows MailerPress > Settings > Sign-up Confirmation. When it is enabled, the contact is pending and receives the confirmation email. See Enable sign-up confirmation (double opt-in).
The visitor sees MailerPress’s reply: “Subscription successful!”, or “Please check your email to confirm your subscription.” when sign-up confirmation is enabled. Errors from MailerPress are shown as is. Your Rate limit message appears when the limit is reached.
When honeypot protection is enabled in Spam Protection, the form includes a hidden field that filters out bots.
The contact’s opt-in source is embed_form.

Manage your API keys

The Embed Forms page lists your keys with their Status, Domain (Any when no domain is set), Rate Limit, Total Requests and creation date. From the list you can:

Click Embed Code on an active key to generate the form code again.
Edit a key’s name, allowed domains, rate limit or notes. The key itself does not change, so existing forms keep working.
Revoke a key to stop it immediately. You can activate it again later.
Delete a key permanently. Forms that use it stop working.

To act on several keys at once, select them and use Revoke Selected, Activate Selected or Delete Selected.

Troubleshooting

“Domain not authorized”: the external page’s domain is not in Allowed Domain. Domains must match exactly: example.com does not cover www.example.com, so add both if needed.
“Authentication failed”: the key is wrong, revoked or deleted, or YOUR_API_KEY_HERE was not replaced.
Visitors see the rate limit message: raise Maximum Requests or shorten Time Window (minutes) for this key.
The form does not appear: check that the script URL opens in your browser and that the page contains the mailerpress-embed container.