smartest.website integration guide

Prepare your form

Create and publish a signup form with a required email field and a required consent checkbox. Add your privacy notice, enable “Double opt-in for connected apps”, and choose the confirmation email language. Only active, valid forms with this setting enabled appear in smartest.website.

Connect smartest.email from the intended smartest.website website, sign in here, and explicitly choose the organization that owns the form. The connection is separate from smartest.website sign-in and billing. Access requires settings:edit and form:view; submitting subscriptions also requires contact:create.

Map the returned fields using their exact names and show the current consent text and privacy notice. Never preselect consent. Each website connection must stay bound to its selected organization; after connecting a different organization, remap its forms and do not replay queued submissions into the new connection.

Authorize a connection

smartest.website uses OAuth authorization code with PKCE S256. Register the client and exact callback URLs with the smartest.email server administrator. Wildcard redirects are not accepted; development callbacks require separate registration. Use a fresh unpredictable state and PKCE verifier for each attempt, and validate the returned state before exchanging the code.

GET https://smartest.email/oauth/authorize
  ?response_type=code
  &client_id=<REGISTERED_CLIENT_ID>
  &redirect_uri=https%3A%2F%2Fmy.smartest.website%2Fsmartest-email%2Fcallback
  &scope=forms%3Aread%20subscriptions%3Awrite
  &state=<OPAQUE_STATE>
  &code_challenge=<BASE64URL_SHA256_VERIFIER>
  &code_challenge_method=S256

The consent screen shows the application, requested permissions and eligible organization. Signing in alone does not grant access. Approval returns a short-lived, single-use code and unchanged state to the registered callback. Declining returns error=access_denied and the same state. Invalid requests do not redirect.

https://my.smartest.website/smartest-email/callback?code=<CODE>&state=<STATE>
https://my.smartest.website/smartest-email/callback?error=access_denied&state=<STATE>

forms:read allows the organization summary and eligible form configuration. subscriptions:write allows pending signup requests for those forms. Tokens cannot access dashboard account APIs, other organizations, or unrelated platform features. The server rechecks account status, membership and permissions when issuing and using access.

Tokens and revocation

Exchange and refresh tokens on your server using application/x-www-form-urlencoded. smartest.website is a confidential client: client authentication is required for token exchange, refresh and revocation. Keep client secrets and access/refresh tokens out of browser bundles, URLs and logs. Authorization codes appear only in the registered callback and are exchanged server-side. These OAuth tokens are distinct from account login tokens.

POST https://api.smartest.email/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<CODE>&redirect_uri=<ENCODED_CALLBACK>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&code_verifier=<VERIFIER>

{
  "access_token": "<OPAQUE_ACCESS_TOKEN>",
  "refresh_token": "<OPAQUE_REFRESH_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "forms:read subscriptions:write"
}

Refresh tokens rotate on every successful refresh. Serialize refreshes for a connection, save the new token pair atomically, and discard the previous refresh token. Reuse of a rotated token invalidates the connection. Expired or revoked access requires refreshing or reconnecting; do not retry authentication indefinitely.

POST https://api.smartest.email/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

POST https://api.smartest.email/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<TOKEN>&token_type_hint=refresh_token&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Revocation is idempotent and returns no token details. Users can also revoke their connections in Settings → Connected apps. Revoking a grant stops future authenticated requests and token refreshes. Handle a revoked connection as disconnected in smartest.website.

Read account and form configuration

Call these server-to-server endpoints with Authorization: Bearer <OAUTH_ACCESS_TOKEN> and forms:read. The account ID identifies the authorized organization, not the person who connected it. The forms list contains every eligible form without pagination and does not increment public view counts.

GET https://api.smartest.email/api/v1/integrations/smartest-website/account
{ "id": "<ORGANIZATION_UUID>", "name": "Example Studio" }

GET https://api.smartest.email/api/v1/integrations/smartest-website/forms
{
  "forms": [{
    "id": "<FORM_UUID>",
    "name": "Newsletter",
    "fields": [
      { "name": "email", "type": "email", "label": "Email", "required": true },
      { "name": "firstName", "type": "text", "label": "First name", "required": false },
      { "name": "consent", "type": "checkbox", "label": "I agree to receive marketing emails.", "required": true }
    ],
    "consent_text": "I agree to receive marketing emails.",
    "privacy_url": "https://example.com/privacy",
    "double_opt_in": true
  }]
}

Preserve field names, types, required flags, choices and validation constraints. Names such as firstName are case-sensitive. An empty forms list means no eligible forms are available; it is not an authentication failure. Unpublished, invalid, foreign or non-opt-in forms cannot accept smartest.website submissions.

Submit a signup request

Use subscriptions:write and a stable Idempotency-Key for each original website submission. Send only configured fields inside data, excluding consent. Values are strings or booleans; numeric fields use numeric strings, dates use YYYY-MM-DD, and choice values must match the configured options.

POST https://api.smartest.email/api/v1/integrations/smartest-website/forms/<FORM_UUID>/subscribe
Authorization: Bearer <OAUTH_ACCESS_TOKEN>
Content-Type: application/json
Idempotency-Key: <STABLE_UNIQUE_SUBMISSION_KEY>

{
  "data": { "email": "reader@example.test", "firstName": "Reader" },
  "consent": {
    "granted": true,
    "text": "I agree to receive marketing emails.",
    "occurred_at": "2026-10-19T10:30:00Z"
  },
  "source": {
    "site_id": "<WEBSITE_UUID>",
    "form_id": "<FORM_UUID>",
    "submission_id": "12345"
  },
  "double_opt_in": true
}

HTTP/1.1 202 Accepted
{ "accepted": true }

consent.text must match the current consent label after trimming; stale wording is rejected. occurred_at is the actual RFC3339 consent time, including for queued delivery. Source IDs record provenance only and never authorize access. The complete site, form and submission tuple identifies the original smartest.website event.

202 means the request and consent evidence have been durably accepted. A confirmation email is queued only for an eligible new address; existing or suppressed addresses receive the same response without an email. It does not mean the address is subscribed or the email has been delivered. Ask the visitor to check their email if eligible, without revealing address status or claiming a completed subscription.

The email opens a page with an opaque token in the URL fragment. Loading the page does nothing to the subscription; the reader must select Confirm subscription. Confirmation links expire and are single-use. Repeated valid confirmation is safe. Existing unsubscribed, bounced, complained or suppressed addresses are never silently resubscribed, retagged or enrolled; responses do not reveal address status.

https://smartest.email/subscribe/confirm#token=<OPAQUE_TOKEN>

POST https://api.smartest.email/api/v1/public/subscriptions/confirm
Content-Type: application/json

{ "token": "<OPAQUE_TOKEN>" }

{ "confirmed": true }

Responses and safe retries

Retry a timeout or temporary server failure using the same idempotency key and unchanged payload. A matching retry returns the original acceptance and creates no duplicate confirmation email, consent record or subscription. Reusing the key with another form or payload returns 409. Store the key with the queued submission and keep it across retries and token refreshes.

{ "error": "Invalid consent", "code": "invalid_consent" }

Limits protect each connection, organization and recipient address. Queue responsibly and use bounded retries. Do not treat 202 as proof of deliverability or consent confirmation. Monitor failures without recording tokens, secrets, full payloads or confirmation links.

Before enabling a production website, verify the complete round trip: authorize, load the correct organization and form, submit explicit consent, receive and confirm the email, then revoke the connection and verify new requests fail. Provider documentation alone does not verify a particular smartest.website installation.