양식
`forms->list`, `listAll`, `iterate`, `get`, `create`, `design`, `redesign`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `listStarters`, `getStarter`, `listSubmissions`, `getSubmission`, `deleteSubmission`, `deleteSubmissions`, `approveSubmission`, `resendConfirmation`, `subscribe`.
모든 메서드
use OpenEmail\Constants\FormStarterSlugs;use OpenEmail\Constants\FormSubmissionStatuses; $form = $client->forms->create([ 'name' => 'Newsletter sign-up', 'starter' => FormStarterSlugs::NEWSLETTER, 'settings' => ['audienceIds' => ['aud_4c1b8e2a7d9f05c36b4e8a71']], 'publish' => true,]); echo $form['url'], ' ', $form['subscribeUrl'], PHP_EOL; $saved = $client->forms->update($form['id'], [ 'settings' => ['doubleOptIn' => true, 'senderAddress' => '[email protected]'], 'expectedUpdatedAt' => $form['updatedAt'],]); $signup = $client->forms->subscribe($form['id'], [ 'email' => '[email protected]', 'first_name' => 'Ann', 'consent' => true,]); foreach ($client->forms->iterateSubmissions($form['id'], status: FormSubmissionStatuses::PENDING) as $submission) { if ($submission['expired']) { $client->forms->resendConfirmation($form['id'], $submission['id']); }} $stats = $client->forms->analytics($form['id'], days: 30);$starters = $client->forms->listStarters(); $client->forms->pause($form['id']);$client->forms->resume($form['id']);$copy = $client->forms->duplicate($form['id']);$client->forms->delete($copy['id']); echo $saved['senderIssue'] ?? 'ready to send', ' ', $signup['outcome'], ' ', $stats['totals']['conversion'] ?? 'no views yet', ' ', count($starters), PHP_EOL;양식은 초안인 document와 방문자에게 보이는 publishedDocument를 보관합니다. update는 초안과 설정을 바꾸고, publish는 초안을 게시합니다. 설정은 게시 여부와 상관없이 즉시 적용되며, expectedUpdatedAt은 다른 사람의 저장을 덮어쓰게 될 저장을 409 version_conflict로 거부하고, 이는 ConflictException으로 던져집니다.
양식의 필드는 API의 camelCase 이름(expectedUpdatedAt, doubleOptIn)을 쓰는 배열 하나의 키이고, 필터와 옵션은 명명된 인자입니다(listSubmissions의 status:, analytics의 offsetMinutes:). 양식은 camelCase 키를 가진 배열로 돌아오므로, $form['subscribeUrl']로 가입을 받는 주소를 읽습니다.
design은 앱의 양식 페이지에 있는 AI로 만들기처럼, 글로 쓴 요청으로 새 초안 양식을 만들고, redesign은 양식 빌더의 AI에게 요청처럼, 양식의 초안에 글로 쓴 지시를 적용합니다. 각각 AI 작업 1회를 쓰며 초안만 쓰므로, publish 전까지 방문자에게는 새로운 것이 보이지 않습니다.
읽기에는 forms:read, 변경에는 forms:write가 필요합니다. approveSubmission은 연락처를 추가하므로 contacts:write도 필요합니다. resendConfirmation에는 emails:send도 필요하며, 양식이 메일을 보내게 하는 호출에도 필요합니다: doubleOptIn 켜기, senderAddress나 확인 메일 설정, 더블 옵트인 양식의 게시나 재개가 여기에 해당합니다. delete는 OAuth 액세스 토큰에는 인증 코드를 요구하지만, API 키에는 절대 요구하지 않습니다. 토큰이 코드를 얻기 전까지 delete는 isStepUpRequired()가 true인 PermissionException을 던집니다.
subscribe는 양식의 페이지와 똑같이 누군가를 가입시키며, 자격 증명을 가진 클라이언트에서도 자격 증명을 보내지 않으므로 apiKey:는 무시됩니다. 답변은 두 번째 인자로, 양식의 필드 키를 키로 하는 배열 하나입니다. 한 네트워크에서 오는 모든 가입은 10분마다 40번이라는 한도를 함께 쓰므로, 많은 사람의 가입을 중계하는 서버는 금방 한도에 닿습니다: 이미 아는 사람은 대신 audiences->importContacts로 추가하세요. 한도를 넘으면 호출은 RateLimitException을 던집니다. 양식이 있던 페이지는 oe_source로 넘기고, oe_started는 빼고, oe_website는 빈 값으로 보내거나 아예 빼세요.
subscribe에서 오는 422는 invalid_form_submission이며 ValidationException으로 던져지고, 예외의 fields는 빠졌거나 유효하지 않은 답변을 각각 key와 error를 가진 배열로 나열하며 required, email, option 같은 이유를 담습니다. OpenEmail\Constants\FormFieldErrors가 모든 이유를 정의합니다. 패키지는 서버에서 실행됩니다. 브라우저는 양식의 subscribeUrl로 답변을 직접 전송하며, JSON 본문으로 보내거나 Accept: application/json 헤더를 붙이면 어떤 오리진에서든 JSON을 돌려받습니다. 둘 다 없으면 호스팅된 페이지로 가는 303 리디렉션을 받습니다.
응답: 양식
list는 document와 settings를 뺀 양식의 OpenEmail\Result\Page 하나를 최신순으로 반환합니다. listAll은 모든 양식을 하나의 배열로 반환하고, iterate는 모든 페이지를 양식 하나씩 순회하는 Generator를 반환합니다. get, create, update, publish, pause, resume, duplicate는 document, publishedDocument, settings, audiences, senderIssue, senderProblem을 더한 양식 전체를 배열로 반환합니다.
idstring- 영구적인 핸들로, `frm_` 뒤에 16진수 24자가 붙습니다.
statusstring- 첫 게시 전까지는 `draft`, 그 뒤로는 가입을 받는 동안 `live`, 받지 않는 동안 `paused`입니다. 양식은 `draft`로 돌아가지 않습니다. `OpenEmail\Constants\FormStatuses`가 이 세 가지를 정의합니다.
urlstring- 게시된 양식의 호스팅된 페이지로, 링크로 공유할 수 있습니다.
subscribeUrlstring- 순수 HTML 양식이나 브라우저의 스크립트가 답변을 전송하는 곳입니다.
documentarray- 초안: 순서대로 놓인 `fields`, 그 주변의 `copy`, 그리고 `style`.
publishedDocumentarray or null- 방문자에게 지금 보이는 내용입니다. 첫 게시 전까지는 null입니다.
settingsarray- 가입이 들어갈 곳과 가입 뒤에 일어나는 일: `audienceIds`, `doubleOptIn`, `senderAddress`, 확인 메일, `successAction`, `redirectUrl`, `notifyAddresses`.
hasUnpublishedChangesbool- 초안이 방문자에게 보이는 내용과 다르면 true입니다. 첫 게시 전에는 항상 false입니다.
senderIssuestring or null- 더블 옵트인 양식이 지금 확인 메일을 보낼 수 없는 이유입니다: `missing`, `not_sendable`, `not_allowed` 중 하나입니다. 보낼 수 있으면 null입니다. `OpenEmail\Constants\FormSenderIssues`가 이 세 가지를 정의합니다.
statsarray- `views`, `submissions`, `added`, `pending`, `lastSubmittedAt`이며, 조회 시점에 집계됩니다.
제출
listSubmissions는 이메일 주소를 검색하는 q:, pending 또는 added를 고르는 status:와 함께 최신순으로 페이지를 가져오고, listAllSubmissions와 iterateSubmissions가 모든 페이지를 훑습니다. OpenEmail\Constants\FormSubmissionStatuses가 두 상태를 정의합니다. 각 제출은 답변을 라벨까지 포함해 보낸 그대로 보관하는 배열이므로, 양식이 바뀐 뒤에도 제대로 읽힙니다.
resendConfirmation은 confirmationSent가 담긴 제출을 반환합니다. 아무것도 나가지 않았으면 false입니다: 한 주소는 양식마다 10분에 한 통, 워크스페이스 전체에서 하루 다섯 통의 확인 메일을 받으며, 이미 추가된 제출은 받지 않습니다. expired는 최신 링크가 만료된 확인 대기 중인 가입을 표시합니다.