BizKitHub
DocsAPI ReferenceNewsletter/api/v1/newsletter/register-contact
postNewsletterPublic API v1

/api/v1/newsletter/register-contact

Registers a new contact for the newsletter. If the contact already exists, it is updated with the provided data. Optionally assigns the contact to one or more newsletter groups.

By default the contact receives the newsletter-onboarding-contact e-mail with a confirmation link (double opt-in) and the subscription is active after the click. Organisations with single opt-in enabled can skip the confirmation by sending consent (see the field). Contacts who opted out before are never re-subscribed without confirmation.

newsletterpostApiV1NewsletterRegister-contact

Parameters

1 query · JSON body

Query parameters

· 1
apiKeystringRequired

Your BizKitHub API key (passed as GET parameter).

Key format: A 32-character string matching: ^(PROD|DEV_|ROOT)[A-Za-z0-9]{28}$
Prefixes: PROD (production key), DEV_ (individual developer), ROOT (system key with no limits). Learn more

ExamplePRODPGrFxpGEtrOZfuWhnoJohUYBXuOE

Request body

application/json
emailstringRequired

Contact email address.

The system validates the input as a standard email address and automatically applies normalization and canonicalization.

All API responses return the normalized form, and each email address is unique per organisation within the system.

Phone-only contacts: Since 2026-06-10 a contact may exist without an e-mail when it was registered only by phone (e.g. imports of phone-only records). Responses that expose such contacts use API_EMAIL_NULLABLE instead, where this field can be null. Endpoints that accept e-mail as input still require a valid value here — phone-only creation goes through admin-only import / BFF flows.

sourcestringOptional

Signup source identifier for analytics.

Exampleswebfootersocial
groupsstring[]Optional

Newsletter group tags to assign to the contact.

phonestringOptional

Contact phone number in international (national) format.

Preferred format: +<country_code> <local_number>

  • Leading plus sign (+) is required
  • Followed by the country calling code (e.g. 420)
  • One space after the country code
  • Full local number without spaces

Example: +420 777123456
This format ensures unambiguous storage, validation, and compatibility with SMS, calling, and third-party integrations (e.g. Twilio, WhatsApp, CRM systems).

Example+420 777123456
firstNamestringOptional
ExampleJan
lastNamestringOptional
ExampleBarášek
consentobjectOptional

Proof of the newsletter consent given at the form. Required for single opt-in: when the organisation enabled "Newsletter without confirmation" (config newsletter_single_opt_in) and this object is sent, the subscription is active immediately, the consent is recorded (wording, page URL, user agent, IP as geo record) and the contact receives the newsletter-welcome-contact e-mail with an unsubscribe link instead of the confirmation e-mail. Without it, or for contacts who unsubscribed before, double opt-in applies.

textstringRequired

Exact consent wording shown next to the form, stored verbatim as proof of consent.

Length: 1–2000
ExampleZadáním e-mailu se přihlašuješ k odběru novinek GymRoom. Odhlásit se můžeš kdykoli.
urlstringOptional

URL of the page with the form.

Length: 0–500
Examplehttps://gymroom.cz/
userAgentstringOptional

Visitor's browser user agent. Send it when calling from a server; defaults to the request's User-Agent.

Length: 0–500
customerRealIpstringOptional

User IP address used for GEO/IP intelligence.

Accepted formats:

  • IPv4 dot-decimal, e.g. 1.1.1.1 (4 octets, 0–255, no leading zeros).
  • IPv6 as defined by RFC 4291 — full 2001:0db8:0000:0000:0000:0000:0000:0001, zero-compressed 2001:db8::1, IPv4-mapped ::ffff:1.2.3.4, or scoped literals. Both upper- and lower-case hex are accepted.

Server-side canonicalization (ipNormalize in core/src/lib/network/ipNormalize.ts):

  • Valid IPv4 is passed through verbatim.
  • Valid IPv6 is lowercased (RFC 5952 §4.3).
  • IPv4-mapped IPv6 ::ffff:X.X.X.X is unwrapped to plain IPv4 (RFC 4291 §2.5.5.2) so 1.2.3.4 and ::ffff:1.2.3.4 share one brj__geo_ip row.
  • Loopback aliases (::1, 0.0.0.0, localhost, empty string) collapse to 127.0.0.1.
  • Junk values that fail both IPv4 and IPv6 validation are silently rejected and replaced with 127.0.0.1 (loopback).

On the wire: every response returns the canonicalized form — clients can safely rely on lowercase IPv6 and the plain-IPv4 unwrap when de-duping or joining. Server-originated writers (activity log, session log, ban list) resolve the visitor IP via resolveClientIp / resolveClientIpOrNull — always native IPv6 on Vercel Edge (there is no auto-mapping to ::ffff:X.X.X.X).

Enrichment: the system resolves reverse DNS, geolocation, ASN, mobile/proxy/hosting/Tor flags via our VikiTron GEO/IP resolver for both address families. Learn more

Examples1.1.1.12001:4860:4860::8888

Response schema

1 status code documented

200Success
success"true"Required
confirmedbooleanRequired

True when the subscription is active right away (single opt-in). False when a confirmation e-mail was sent or the contact was already on the list / opted out.

Response example

application/json
{
  "success": true,
  "confirmed": false
}

Request example

POST /api/v1/newsletter/register-contact

post
curl -X POST "https://api.bizkithub.com/api/v1/newsletter/register-contact?apiKey=PRODPGrFxpGEtrOZfuWhnoJohUYBXuOE" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "email": "[email protected]",
  "source": "web",
  "groups": [
    "trainer"
  ],
  "phone": "+420 777123456",
  "firstName": "Jan",
  "lastName": "Barášek",
  "consent": {
    "text": "Zadáním e-mailu se přihlašuješ k odběru novinek GymRoom. Odhlásit se můžeš kdykoli.",
    "url": "https://gymroom.cz/",
    "userAgent": "example_userAgent"
  },
  "customerRealIp": "1.1.1.1"
}'

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key