API reference

The API lets your own systems add contacts, push products and send transactional email. Available on Starter and above.

Authentication

Create a key under Settings → Integrations → API keys. Keys belong to one brand, so the key you use decides which brand the data lands in. Send it as a bearer token:

Authorization: Bearer YOUR_API_KEY

The header x-api-key is accepted as an alternative. Keys are shown once at creation and stored only as a hash, so a lost key must be replaced rather than recovered.

Add or update a contact

curl -X POST https://www.nectazo.com/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "person@example.com",
    "firstName": "Jordan",
    "lastName": "Reyes",
    "source": "website-signup",
    "listId": "YOUR-LIST-UUID",
    "customFields": { "plan": "trial" }
  }'

Suppression is respected: an address that previously unsubscribed is not resubscribed by an API call.

Enrich many contacts at once

Sets custom fields on contacts you already have — up to 500 per request, in one round trip. For anything annotating an existing list this is the endpoint to use: doing the same job one address at a time turns a few milliseconds of work into a minute and a half of latency.

curl -X POST https://www.nectazo.com/v1/contacts/enrich   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "contacts": [
      { "email": "ada@example.com", "customFields": { "plan": "annual" } },
      { "email": "grace@example.com", "customFields": { "plan": "monthly" } }
    ]
  }'

It answers with how many were updated and how many of the addresses are not contacts, with the first fifty of those named:

{ "updated": 1, "notFound": 1, "notFoundEmails": ["grace@example.com"] }

• Custom fields are merged, so sending one key leaves every other field on the contact alone.
• It never creates anybody. An address that is not a contact is counted and named, not added — which also means it can never trigger an opt-in email.
• It cannot change a subscription status, add anyone to a list, or unsubscribe anyone. Use the single-contact endpoint for those.
• A duplicated address within one request is applied once, and the last one wins.

Send a transactional email

curl -X POST https://www.nectazo.com/v1/transactional \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "person@example.com",
    "type": "password_reset",
    "subject": "Reset your password",
    "html": "<p>Click <a href=\"https://example.com/reset\">here</a> to reset.</p>"
  }'

type is your own label — it groups messages on the Transactional page, so keep it consistent.

Push products

POST /v1/products accepts batches of products and is what the WordPress plugin uses. Unless you are building your own integration, use the plugin instead.

List your forms

GET /v1/forms returns the published forms in the key's brand — enough to name one and to know how it opens. Drafts are left out, since a draft renders nothing.

curl https://www.nectazo.com/v1/forms   -H "Authorization: Bearer nk_live_..."

{
  "forms": [
    {
      "id": "9a8cddd7-...",
      "name": "Free guide popup",
      "type": "popup",
      "trigger": "click",
      "clickSelector": "[data-nectazo-open]"
    }
  ]
}

It exists so an integration can offer a list to choose from rather than a box to paste an id into — the WordPress plugin uses it for exactly that. trigger is included because a caller offering several forms at once needs to know which of them open on their own: two of those on one page is two things covering the screen.

Responses and errors

Keeping keys safe

• Server-side only. A key in browser JavaScript is a public key.
• One key per system, so you can revoke one without breaking the others.
• Revoke immediately if a key is exposed — revocation takes effect at once.