Newsletter signup
Add a signup form to your own website that joins people to your Lahuta newsletter.
Use this when you want a newsletter signup box on your own site, in the footer, on a popup or at the end of a blog post, and you want the people who sign up to land in your Lahuta newsletter.
One call does it all: the person becomes a contact, joins your newsletter, and gets a confirmation email if you ask for one.
Subscribe someone
POST /v1/newsletter/subscribe needs an email. Everything else is optional.
curl -X POST https://api.lahuta.org/v1/newsletter/subscribe \
-H "X-Api-Key: $LAHUTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "sam.okafor@example.com",
"contact": { "firstName": "Sam" },
"topics": ["Class announcements"],
"source": "footer"
}'{
"pending": false,
"contactId": "0197b30a-51c2-7e84-9b0d-6f2a8c3e1d57",
"topics": [
{
"id": "0197a1f4-2d93-7b06-a8c5-4e1b9f7d3a20",
"name": "Class announcements",
"created": false
}
]
}The request
| Field | Required | What it does |
|---|---|---|
email | Yes | The address that's subscribing. Only this address is subscribed, even if contact lists others |
contact | No | What your form knows about the person: firstName, lastName, phones and any other contact field. Saved the same way as PUT /v1/contacts |
topics | No | Up to 20 topic names to join. Leave it out to join your default topics |
source | No | Where on your site the signup came from, like footer or pottery-fair-popup. Up to 64 characters |
Without a first name, Lahuta makes one from the email address. sam.okafor@example.com becomes "Sam Okafor". Send firstName if your form asks for it.
source is saved as a slug next to the subscriber, so you can see which of your forms bring people in. On the Members tab of Marketing → Newsletter, these signups show as API followed by the source, like "API · footer". Only a person's first signup sets it.
Confirmation emails
pending tells you what to say on your thank-you message:
"pending": false: the person is subscribed now."pending": true: Lahuta sent them an email with a link to confirm. They join once they click it.
Which one you get depends on the Require confirmation switch under Marketing → Newsletter, in the Confirm subscriptions card. It's off by default. Turn it on to keep typos and fake addresses off your list.
Someone who's already subscribed stays subscribed, and someone waiting to confirm stays waiting. Signing up twice is never an error, so you don't need to check first.
Topics
Topics are the lists inside your newsletter, like "Class announcements" or "Shop news". Topic names are matched ignoring upper and lower case.
- Leave out
topicsto join the topics marked Subscribe new members by default in the dashboard. This is what most signup forms should do. - Name topics to join exactly those, for example a "Kiln opening sale" box that only signs people up for sale news.
- A topic that doesn't exist yet is created.
created: truein the response tells you so. A topic made this way isn't a default topic, so a typo in your code won't start collecting everyone else's signups. Fix the name in your code and delete the stray topic under Marketing → Newsletter → Topics.
Edge cases
- An invalid email address is refused with a
400and no body. Validate the format on your form first so people get a quick answer. - Bots. Signup forms attract spam. Add a honeypot field or a CAPTCHA to your form, and consider turning on Require confirmation.
- Unsubscribing happens through the link in every newsletter email. There's no Org API call for it.
- The contact is created or updated like any other contact, so the person shows up in CRM with the rest of your customers.
See Newsletter in the API reference for every field.