How-to
Subscribe URL
Every audience has a subscribe URL that adds people without an API key. Learn the request format, how double opt-in changes it, how to call it safely, its limits and how to reset it.
Each audience has a subscribe URL: a public endpoint that adds a person to the audience without an API key. Use it to connect a sign-up form on your site, or a no-code tool that can send a JSON request, to an audience. It’s an endpoint for POST requests, not a page: opening it in a browser doesn’t subscribe anyone.
POST https://api.emailit.com/subscribe/{token}The token is secret to the audience. Anyone who has the URL can add addresses to the audience, so treat it like a password.
Find the URL
-
Open the audience. Go to Email MarketingAudiences and select the audience.
-
Copy the URL. Select Subscribe URL and copy the URL from the dialog. The dialog also shows an example request and whether double opt-in is on.
With the API, Retrieve an audience returns the same value in token.
Request format
Send a POST request with a JSON body and Content-Type: application/json. No Authorization header is needed.
emailstringrequiredfirst_namestringlast_namestringcustom_fieldsobjectThe endpoint only reads JSON. Form-encoded bodies, which a plain HTML <form> sends, are rejected with 400 and “Invalid JSON in request body”.
Responses
| Status | Body | When |
|---|---|---|
200 |
{ "message": "Subscribed successfully", "status": "subscribed" } |
Double opt-in is off, and the person was added, resubscribed or was already subscribed. |
202 |
{ "message": "Check your inbox to confirm the subscription.", "status": "pending" } |
Double opt-in is on: the double opt-in email was sent and the person joins when they click its link. People who are already subscribed, or signed up again right after the first time, get the same answer without a new email. |
400 |
{ "error": "Missing required field: email" } or { "error": "Invalid email format" } |
The email is missing or malformed, or the body isn’t JSON. |
403 |
{ "error": "Workspace suspended" } or { "error": "Workspace scheduled for deletion" } |
The workspace is suspended or scheduled for deletion, so it takes no sign-ups. |
404 |
{ "error": "Audience not found" } |
The token is wrong or was reset, or the audience is archived. |
422 |
{ "error": "...", "usage": { ... } } |
The audience reached its subscriber limit. |
429 |
More than 30 requests in a minute from the same IP address, or, when double opt-in or the confirmation email is on, too many sign-ups for the audience or from your network in the last hour. Try again after the number of seconds in the retry-after header. |
|
503 |
{ "error": "The double opt-in email could not be sent. Please try again later.", "code": "..." } |
Double opt-in is on but the double opt-in email couldn’t be sent, for example because the sending domain isn’t verified or the workspace is out of credits. The person isn’t added. |
What a sign-up does
- New address: Emailit creates the contact and subscribes it to the audience.
- Existing contact, not on the audience: Emailit updates the names and custom fields you sent and subscribes the contact.
- Existing subscriber who had unsubscribed: Emailit subscribes them again.
- Existing subscriber who is subscribed: nothing changes, and the response is still
200.
With double opt-in on, a new contact is created right away, an existing contact’s names and custom fields aren’t changed, and the subscription waits until the person clicks the link in the double opt-in email.
A new subscription sends subscriber.created (or subscriber.updated for a resubscribe) webhook events, starts Added to audience automations and sends the audience’s confirmation email when it’s on. Sign-ups don’t send contact.* events and don’t change a contact’s marketing status: if the contact was globally unsubscribed, campaigns keep skipping it until you resubscribe it on the Contacts list.
Connect a sign-up form
The subscribe URL has no bot protection, and it only accepts JSON. The safest setup is to post your form to your own server, check it there, and call the subscribe URL from the server. That keeps the token out of your page source and lets you block spam before it reaches your audience.
-
Add the form to your page. Post it to an endpoint on your own site. The hidden
websitefield is a honeypot: people don’t see it, but bots often fill it in.<form id="signup" method="post" action="/newsletter"> <label for="email">Email</label> <input id="email" name="email" type="email" required> <label for="first_name">First name</label> <input id="first_name" name="first_name" type="text"> <!-- Honeypot: hidden from people, often filled in by bots --> <div style="position:absolute;left:-10000px" aria-hidden="true"> <input name="website" type="text" tabindex="-1" autocomplete="off"> </div> <button type="submit">Subscribe</button> <p class="status" role="status"></p> </form> -
Handle the form on your server. Drop honeypot hits, check a CAPTCHA if you use one, then forward the fields to the subscribe URL as JSON. Keep the token in an environment variable such as
EMAILIT_SUBSCRIBE_TOKEN. See the server examples below. -
Test it. Submit the form with your own address and check that you appear in the audience’s subscribers table.
Server examples
import express from 'express';
const app = express();
app.post('/newsletter', express.urlencoded({ extended: false }), async (req, res) => {
// Bots fill in the honeypot. Pretend it worked and stop.
if (req.body.website) return res.redirect(303, '/thanks');
const response = await fetch(
`https://api.emailit.com/subscribe/${process.env.EMAILIT_SUBSCRIBE_TOKEN}`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: req.body.email,
first_name: req.body.first_name || undefined,
}),
},
);
if (!response.ok) {
const { error } = await response.json().catch(() => ({}));
return res.status(response.status).send(error || 'Could not subscribe.');
}
res.redirect(303, '/thanks');
});
app.listen(3000);<?php
// Bots fill in the honeypot. Pretend it worked and stop.
if (!empty($_POST['website'])) {
header('Location: /thanks', true, 303);
exit;
}
$token = getenv('EMAILIT_SUBSCRIBE_TOKEN');
$ch = curl_init("https://api.emailit.com/subscribe/{$token}");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'email' => $_POST['email'] ?? '',
'first_name' => $_POST['first_name'] ?? null,
]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 300) {
http_response_code($status);
echo json_decode($body, true)['error'] ?? 'Could not subscribe.';
exit;
}
header('Location: /thanks', true, 303);curl "https://api.emailit.com/subscribe/$EMAILIT_SUBSCRIBE_TOKEN" \
-X POST \
-H "Content-Type: application/json" \
-d '{ "email": "ada@example.com", "first_name": "Ada" }'If your page submits with JavaScript instead of a full page load, call your own endpoint with fetch and keep the Emailit call on the server:
document.querySelector('#signup').addEventListener('submit', async (event) => {
event.preventDefault();
const form = new FormData(event.target);
const response = await fetch('/newsletter', { method: 'POST', body: new URLSearchParams(form) });
event.target.querySelector('.status').textContent = response.ok
? 'Thanks, you are subscribed.'
: 'Something went wrong. Please try again.';
});Rate limit and higher volumes
The subscribe URL accepts 30 requests per minute from each IP address and returns 429 above that. When your server forwards every sign-up, they all come from your server’s IP, so the 30 per minute apply to your whole site. When double opt-in or the confirmation email is on, sign-ups also have fair use limits per audience and per network, because each one sends an email. If you expect more, call Add a subscriber from your server with an API key instead. That endpoint also returns 409 for people who are already subscribed, and takes "double_opt_in": true to ask for confirmation.
Confirm sign-ups
Turn on double opt-in on the audience’s Settings tab to make every sign-up through the subscribe URL confirm their address first. The URL then returns 202, Emailit sends the double opt-in email from your verified domain, and the person joins when they click its link. Your form can show “Check your inbox” when it gets 202.
To welcome people once they’re on the list, turn on the audience’s confirmation email.
Reset the URL
Reset the token if the URL leaked or you’re getting spam sign-ups. The old URL stops working immediately and returns 404.
-
Open the dialog. On the audience page, select Subscribe URL.
-
Reset. Select Reset token and confirm. Emailit generates a new URL.
-
Update your integrations. Replace the token everywhere you use it, such as the
EMAILIT_SUBSCRIBE_TOKENvariable on your server.
Resetting the token is only available in the dashboard.