Sign-ups from your site

Keep your own sign-up box. When someone submits it, your server sends their email to YouGrow with the launch's site key. YouGrow confirms the address by email, then the person joins the launch like anyone else: its journey, its broadcasts and its weekly newsletter.

Newsletter or app user? People you send to API v2 users get onboarding journeys only, never broadcasts or the weekly newsletter. A newsletter list is a launch, filled from your box with this call.

Who gets which emails

How they got in	What they get
YouGrow's page or widget	The launch's journey and its broadcasts. The weekly newsletter once they reach its weekly step.
Your own form, with a site key	The same: the launch's journey, its broadcasts, and the weekly newsletter once they reach its weekly step.
Your app, through the API (users.update)	Onboarding journeys only. Never broadcasts or the weekly newsletter.

Before you start

In YouGrow, make a launch for the newsletter and publish its journey, with the weekly newsletter step on its Exit. The steps are in Newsletter from your own site.
On the launch's Page & widget tab, choose Your own form and press Create site key. You get a key id (ygl_…) and a secret (ygls_…, shown once). Store both in your server's secret manager.
Optional: set Send them to, the page people land on after confirming.

Add a sign-up

POST /api/v2/signups with HTTP Basic auth: the key id as the username and the secret as the password. The launch comes from the key. Server to server only: never put the secret in a page or an app.

curl

curl https://yougrow.ai/api/v2/signups \
  -u "$YOUGROW_KEY_ID:$YOUGROW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","locale":"en-GB","source":"blog/first-post"}'

Node (fetch)

const res = await fetch("https://yougrow.ai/api/v2/signups", {
  method: "POST",
  headers: {
    Authorization: "Basic " + Buffer.from(`${process.env.YOUGROW_KEY_ID}:${process.env.YOUGROW_SECRET}`).toString("base64"),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email, locale: "en-GB", source: "blog/first-post" }),
});
// Whatever it answers, tell your visitor: "Check your inbox to confirm."

Fields

Field	Type	Notes
email	string	Required. The address to confirm and subscribe.
firstName	string	Optional. Used in the greeting.
locale	string	Optional, e.g. en-GB. Their emails use it when the launch offers that language.
source	string	Optional, up to 200 characters. Where on your site they signed up, e.g. blog/first-post.

Any other field is refused with a 400.

Responses

Status	Body	What it means
202	confirmation_sent	The confirmation email is on its way.
200	already_confirmed	They're already on the list. Nothing was sent.
200	not_sent: recently_sent	A confirmation went to this address in the last day.
200	not_sent: blocked	Email to this address bounced or was reported as spam. It's never emailed.
200	not_sent: removed	Someone took them off the launch.
400	invalid	A field is wrong: fields lists each problem. Fix it; don't retry as it is.
401	unauthorized	The key id or secret is wrong, or the key was revoked.
404	site_signups_disabled	Sign-ups from your site aren't turned on for this YouGrow.
409	launch_closed	The launch is archived.
413	body_too_large	The body is over 8 KB.
429	rate_limited	Over the limit. Wait Retry-After seconds.
503	email_unavailable	The confirmation couldn't be sent. Retry after Retry-After.

Every call is safe to repeat: the same email on the same launch is one sign-up, and one email a day at most.

What happens next

YouGrow emails the person from the brand's address, asking them to confirm.
The link opens a page with a Confirm subscription button. Opening the link changes nothing, so email scanners can't confirm for anyone.
Once they press it, they go to your Send them to page and join the launch's journey.
The journey's weekly step puts them on the weekly newsletter.

Unsubscribes are handled in YouGrow. No webhook tells your server about these people, so don't keep a second mailing list of them. Someone who unsubscribed before can sign up again: confirming lifts their unsubscribe. A bounced address or a spam report is never lifted.

Limits

60 calls a minute and 1,000 an hour, per key.
8 KB per call.
One confirmation email per address per launch a day.

Keys

One key per launch. It can only add sign-ups to that launch, and it can't read anyone.
Rotate secret gives a new secret; the old one keeps working for 24 hours, so you can switch without missing sign-ups.
Revoke key stops it within a minute. A product's API key never works here, and a site key never works on API v2.

Good practice

Show your visitor the same "Check your inbox to confirm" message whatever the reply.
Keep a honeypot field or a captcha on your box, and limit how often one visitor can submit it.
Retry a 429 or a 503 after Retry-After, and a network error with backoff.