Newsletter signups
Send the addresses from your site's "subscribe" field here, and each project keeps its own list of subscribers.
If your site has a field where people leave their email to hear from you, send the address here. Each project keeps its own list, which you can search, export as CSV and read with a key. Sending mail to the list is not part of this yet: export it and send from the tool you already use.
A signup form, without code
With the browser script on the page, mark the form and give it an email field:
<form data-snekot-subscribe>
<input type="email" name="email" placeholder="[email protected]" required>
<button>Subscribe</button>
<p data-snekot-success hidden>Thanks, you are on the list.</p>
<p data-snekot-error hidden>That did not work. Try again.</p>
</form>
On submit the script sends the address and the page stays where it is. Use a public key, as for everything in a web page.
| In the form | |
|---|---|
data-snekot-subscribe |
Required, on the <form>. |
An <input type="email">, or one named email |
Required. The address. |
An input named name |
The person’s name. |
data-tag-<name>, on the <form> |
A property on the subscriber. data-tag-list="launch" sets list. |
An element with data-snekot-success |
Shown once the address is in. Start it hidden. |
An element with data-snekot-error |
Shown when the address was refused or the server could not be reached. Start it hidden. |
The form also carries data-snekot-state, which is sending, done or error, for styling, and fires snekot:subscribed or snekot:subscribe-failed with the address in event.detail.email. After a signup the form is cleared.
With a field of your own, call the script instead. The promise is true once the address is in:
const ok = await snekot('subscribe', '[email protected]', { plan: 'free' });
From a server or an app
POST https://api.snekot.co/v1/subscribe
{ "email": "[email protected]", "name": "Jane Park", "properties": { "plan": "free" }, "source": "/blog/launch" }
| Field | Type | |
|---|---|---|
email |
string | Required. One address. It is trimmed and stored lowercase. |
name |
string | Up to 200 characters. |
properties |
object | Like a person’s: keys are lowercase letters, digits and dashes, values are strings, numbers or booleans. |
source |
string | The page the signup came from, such as /blog/launch. The browser script fills it in. |
notify |
boolean | Send the signup as a push notification. Off unless set. |
The answer is 200 with { "email": "[email protected]", "subscribed": true }.
Every SDK has the call:
await events.subscribe({ email: '[email protected]', name: 'Jane Park', source: '/blog/launch' });
Signing up twice
An address is on a project’s list once. Signing it up again changes nothing and answers the same as the first time, so a form cannot be used to find out who is on the list.
A public key can only add an address. A private key, which lives on your server, may also set the name and add properties on someone already listed.
In the feed
A new subscriber is also an event, New subscriber in the subscribers channel, with the address as its description and the page as a source tag. So it shows in the feed, a forwarding rule can send it on to Slack or a webhook, and with notify it reaches your phone. A repeat signup posts no event.
If a public key is limited to some channels, add subscribers to them.
Unsubscribing and removing
POST https://api.snekot.co/v1/unsubscribe with { "email": "[email protected]" } marks an address as having left. It stays on the list with the time it left, so an export says who not to write to. If they sign up again later they are subscribed again.
DELETE https://api.snekot.co/v1/subscribers/[email protected] takes an address off for good.
Both need a private key. The usual shape is an “unsubscribe” link in your emails that leads to your own server, which makes the call.
Reading the list
With a read key or a private key:
| Endpoint | Parameters | Answers with |
|---|---|---|
GET /v1/subscribers |
q, limit, cursor |
Subscribers, newest first, with total, unsubscribed and a next cursor. q matches the address, the name and any property. Up to 200 a request. |
GET /v1/export/subscribers.csv |
q |
The whole list as CSV: email, name, subscribed_at, unsubscribed_at, source, properties. |
A key limited to some channels sees the list only if subscribers is one of them.
In the app the list is under People, Subscribers: newest first, with search, the count, a download button for the CSV, and a way to take an address off.
What it counts as
The list itself is not counted against your plan. The New subscriber event is one event of the month, like any other. Past the month’s events the event is held like any other, and at twice them it is left out; the address is always kept, so a signup is never turned away.