POST/forms/{formId}/signups

POST /forms/{formId}/signups

Sign someone up through a form.

View as Markdown

Request

curl -X POST 'https://api.sendheron.com/api/v1/forms/{formId}/signups' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json'

Required scopes

The key must carry these:

  • signups:create

Path parameters

NameTypeRequiredDescription
formIduuidYesA signup form of the workspace the key belongs to.

Body parameters

NameTypeRequiredDescription
emailstringYesThe address that signs up. It gets the confirmation email; nothing happens until its owner confirms.
firstNamestringNoKept only when the form shows a first name field, and required when the form requires it.
lastNamestringNoKept only when the form shows a last name field, and required when the form requires it.
ipAddressstringYesThe visitor's IP address as your server saw it: behind Cloudflare the CF-Connecting-IP header, never an X-Forwarded-For value the visitor can write. Kept on the consent record as reported, and counted toward the per-visitor limit.
userAgentstringNoThe visitor's User-Agent header, kept on the consent record as reported.

Example response

The same for every address: new, already waiting for its confirmation, already subscribed, or one we will not mail.

{
  "status": "ACCEPTED"
}

Responses

Returns 202 on success.

400
The payload failed validation, or the request is not valid for the current state. message says which kind of refusal it is, and for a payload that failed validation (validationFailed) the description names the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". An id in the path that is not a UUID answers invalidUUID on every route.
401
Missing or invalid API key.
403
Valid key, but it does not carry the required scope. message is apiKeys.insufficientScopes and the description names both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was.
404
No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
409
A duplicate, or an idempotency key reused with a different payload.
429
Either rate-limit ceiling was exceeded. message is tooManyRequests, and the Retry-After header says how many seconds until the window rolls.
400
signupForms.invalidEmail, signupForms.undeliverableEmail (the domain takes no mail), signupForms.fieldRequired (the form requires a name), or a body field we do not take
403
The key lacks signups:create, or the organization is suspended
404
signupForms.notFound: no such form in this workspace
409
signupForms.unavailable: the form takes no signups; the description says why (SWITCHED_OFF, SENDER_UNDER_REVIEW, NO_SENDER, CONTACT_LIMIT_REACHED and the rest)
429
Too many requests: a limit of this key or of the visitor you reported; Retry-After says when to try again

Rate limits

30/min per key (tighter than the default), counted against the organization's SEND ceiling (200/min). Both windows are one minute. They limit requests; how much mail goes out in a day is under Daily sending.