Forms
`forms.list`, `get`, `create`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `listStarters`, `getStarter`, `listSubmissions`, `getSubmission`, `deleteSubmission`, `deleteSubmissions`, `approveSubmission`, `resendConfirmation` and `subscribe`.
Every method
const form = await openemail.forms.create({ name: 'Newsletter sign-up', starter: 'newsletter', settings: { audienceIds: ['aud_4c1b8e2a7d9f05c36b4e8a71'] }, publish: true,}) console.log(form.url, form.subscribeUrl) const saved = await openemail.forms.update(form.id, { settings: { doubleOptIn: true, senderAddress: '[email protected]' }, expectedUpdatedAt: form.updatedAt,}) const signup = await openemail.forms.subscribe(form.id, { email: '[email protected]', first_name: 'Ann', consent: true,}) for await (const submission of openemail.forms.iterateSubmissions(form.id, { status: 'pending' })) { if (submission.expired) await openemail.forms.resendConfirmation(form.id, submission.id)} const stats = await openemail.forms.analytics(form.id, { days: 30 })const starters = await openemail.forms.listStarters() await openemail.forms.pause(form.id)await openemail.forms.resume(form.id)const copy = await openemail.forms.duplicate(form.id)await openemail.forms.delete(copy.id) console.log(saved.senderIssue, signup.outcome, stats.totals.conversion, starters.length)A form keeps a draft document and the publishedDocument visitors see. update changes the draft and the settings, and publish puts the draft live. Settings take effect at once, published or not, and expectedUpdatedAt refuses a save that would overwrite someone else’s with 409 version_conflict.
Reading needs forms:read and changing needs forms:write. approveSubmission also needs contacts:write, because it adds a contact. resendConfirmation also needs emails:send, and so does a call that makes the form send mail: turning on doubleOptIn, setting senderAddress or the confirmation email, or publishing or resuming a double opt-in form. delete asks an OAuth access token for a verification code, and an API key never.
subscribe signs someone up as the form’s page does and sends no credential, even from a client that holds one. Every sign-up from one network shares a limit of 40 every ten minutes, so a server relaying sign-ups for many people reaches it quickly: add people you already know with audiences.importContacts instead. Pass the page the form was on as oe_source, leave out oe_started, and send oe_website empty or not at all.
A 422 from subscribe is invalid_form_submission, and the error’s fields lists each answer that is missing or not valid as { key, error }, with reasons such as required, email and option. The client is for servers. In a browser, post the answers to the form’s subscribeUrl with fetch, as a JSON body or with an Accept: application/json header, and it answers JSON from any origin. Without either it answers with a 303 redirect to the hosted page.
Response: FormDetailResource
list resolves to one page of FormResource, newest first, without document and settings, and listAll and iterate walk every page. get, create, update, publish, pause, resume and duplicate resolve to a FormDetailResource, which adds document, publishedDocument, settings, audiences, senderIssue and senderProblem.
idstring- The durable handle, `frm_` followed by 24 hex characters.
status'draft' | 'live' | 'paused'- `draft` until the first publish, then `live` while it takes sign-ups and `paused` while it does not. A form never goes back to `draft`.
urlstring- The hosted page of the published form, to share as a link.
subscribeUrlstring- Where a plain HTML form, or `fetch`, posts the answers.
documentFormDocument- The draft: `fields` in order, the `copy` around them and the `style`.
publishedDocumentFormDocument | null- What visitors see now. Null until the first publish.
settingsFormSettings- Where sign-ups go and what happens after one: `audienceIds`, `doubleOptIn`, `senderAddress`, the confirmation email, `successAction`, `redirectUrl` and `notifyAddresses`.
hasUnpublishedChangesboolean- True when the draft differs from what visitors see. Always false before the first publish.
senderIssue'missing' | 'not_sendable' | 'not_allowed' | null- Why a double opt-in form cannot send its confirmation emails right now, or null when it can.
statsFormStats- `views`, `submissions`, `added`, `pending` and `lastSubmittedAt`, counted at the moment of the read.
Submissions
listSubmissions pages newest first, with q to search email addresses and status for pending or added, and listAllSubmissions and iterateSubmissions walk every page. Each FormSubmissionResource keeps the answers as they were sent, labels included, so it still reads right after the form changes.
resendConfirmation resolves to the submission with confirmationSent. It is false when nothing went out: one address gets one confirmation per form every ten minutes and five a day across the workspace, and an added submission gets none. expired marks a pending sign-up whose latest link has run out.
