양식
`forms.list`, `get`, `create`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `list_starters`, `get_starter`, `list_submissions`, `get_submission`, `delete_submission`, `delete_submissions`, `approve_submission`, `resend_confirmation`, `subscribe`.
모든 메서드
form = client.forms.create( name: "Newsletter sign-up", starter: "newsletter", settings: {audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"]}, publish: true) puts form[:url], form[:subscribeUrl] 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) client.forms.iterate_submissions(form[:id], status: "pending") do |submission| client.forms.resend_confirmation(form[:id], submission[:id]) if submission[:expired]end stats = client.forms.analytics(form[:id], days: 30)starters = client.forms.list_starters client.forms.pause(form[:id])client.forms.resume(form[:id])copy = client.forms.duplicate(form[:id])client.forms.delete(copy[:id]) puts saved[:senderIssue], signup[:outcome], stats.dig(:totals, :conversion), starters.size양식은 초안인 document와 방문자에게 보이는 publishedDocument를 보관합니다. update는 초안과 설정을 바꾸고, publish는 초안을 게시합니다. 설정은 게시 여부와 상관없이 즉시 적용되며, expectedUpdatedAt은 다른 사람의 저장을 덮어쓰게 될 저장을 409 version_conflict로 거부하고, 이는 OpenEmail::ConflictError로 발생합니다.
양식의 필드는 API의 camelCase 이름(expectedUpdatedAt:, doubleOptIn)을 그대로 쓰며 키워드 인자나 Hash 하나로 전달하는 반면, 필터와 옵션은 snake_case 키워드 인자입니다(list_submissions의 status:, analytics의 offset_minutes:). 양식은 Symbol 키를 가진 Hash로 돌아오므로, form[:subscribeUrl]로 가입을 받는 주소를 읽습니다.
읽기에는 forms:read, 변경에는 forms:write가 필요합니다. approve_submission은 연락처를 추가하므로 contacts:write도 필요합니다. resend_confirmation에는 emails:send도 필요하며, 양식이 메일을 보내게 하는 호출에도 필요합니다: doubleOptIn 켜기, senderAddress나 확인 메일 설정, 더블 옵트인 양식의 게시나 재개가 여기에 해당합니다. delete는 OAuth 액세스 토큰에는 인증 코드를 요구하지만, API 키에는 절대 요구하지 않습니다. 토큰이 코드를 얻기 전까지 delete는 step_up_required?가 true인 OpenEmail::PermissionError를 발생시킵니다.
subscribe는 양식의 페이지와 똑같이 누군가를 가입시키며, 자격 증명을 가진 클라이언트에서도 자격 증명을 보내지 않으므로 api_key:는 무시됩니다. 답변은 양식의 필드 키를 키로 하는 키워드 인자나 Hash 하나로 전달합니다. 한 네트워크에서 오는 모든 가입은 10분마다 40번이라는 한도를 함께 쓰므로, 많은 사람의 가입을 중계하는 서버는 금방 한도에 닿습니다: 이미 아는 사람은 대신 audiences.import_contacts로 추가하세요. 한도를 넘으면 호출은 OpenEmail::RateLimitError를 발생시킵니다. 양식이 있던 페이지는 oe_source:로 넘기고, oe_started는 빼고, oe_website는 빈 값으로 보내거나 아예 빼세요.
subscribe에서 오는 422는 invalid_form_submission이며 OpenEmail::ValidationError로 발생하고, 오류의 fields는 빠졌거나 유효하지 않은 답변을 각각 key와 error를 가진 Hash로 나열하며 required, email, option 같은 이유를 담습니다. OpenEmail::FORM_FIELD_ERRORS가 모든 이유를 정의합니다. gem은 서버에서 실행됩니다. 브라우저는 양식의 subscribeUrl로 답변을 직접 전송하며, JSON 본문으로 보내거나 Accept: application/json 헤더를 붙이면 어떤 오리진에서든 JSON을 돌려받습니다. 둘 다 없으면 호스팅된 페이지로 가는 303 리디렉션을 받습니다.
응답: 양식
list는 document와 settings를 뺀 양식의 OpenEmail::Page 하나를 최신순으로 반환하고, list_all과 iterate가 모든 페이지를 훑습니다. get, create, update, publish, pause, resume, duplicate는 document, publishedDocument, settings, audiences, senderIssue, senderProblem을 더한 양식 전체를 Hash로 반환합니다.
idString- 영구적인 핸들로, `frm_` 뒤에 16진수 24자가 붙습니다.
statusString- 첫 게시 전까지는 `draft`, 그 뒤로는 가입을 받는 동안 `live`, 받지 않는 동안 `paused`입니다. 양식은 `draft`로 돌아가지 않습니다. `OpenEmail::FORM_STATUSES`가 이 세 가지를 정의합니다.
urlString- 게시된 양식의 호스팅된 페이지로, 링크로 공유할 수 있습니다.
subscribeUrlString- 순수 HTML 양식이나 브라우저의 스크립트가 답변을 전송하는 곳입니다.
documentHash- 초안: 순서대로 놓인 `fields`, 그 주변의 `copy`, 그리고 `style`.
publishedDocumentHash or nil- 방문자에게 지금 보이는 내용입니다. 첫 게시 전까지는 nil입니다.
settingsHash- 가입이 들어갈 곳과 가입 뒤에 일어나는 일: `audienceIds`, `doubleOptIn`, `senderAddress`, 확인 메일, `successAction`, `redirectUrl`, `notifyAddresses`.
hasUnpublishedChangesBoolean- 초안이 방문자에게 보이는 내용과 다르면 true입니다. 첫 게시 전에는 항상 false입니다.
senderIssueString or nil- 더블 옵트인 양식이 지금 확인 메일을 보낼 수 없는 이유입니다: `missing`, `not_sendable`, `not_allowed` 중 하나입니다. 보낼 수 있으면 nil입니다. `OpenEmail::FORM_SENDER_ISSUES`가 이 세 가지를 정의합니다.
statsHash- `views`, `submissions`, `added`, `pending`, `lastSubmittedAt`이며, 조회 시점에 집계됩니다.
제출
list_submissions는 이메일 주소를 검색하는 q:, pending 또는 added를 고르는 status:와 함께 최신순으로 페이지를 가져오고, list_all_submissions와 iterate_submissions가 모든 페이지를 훑습니다. OpenEmail::FORM_SUBMISSION_STATUSES가 두 상태를 정의합니다. 각 제출은 답변을 라벨까지 포함해 보낸 그대로 보관하는 Hash이므로, 양식이 바뀐 뒤에도 제대로 읽힙니다.
resend_confirmation은 confirmationSent가 담긴 제출을 반환합니다. 아무것도 나가지 않았으면 false입니다: 한 주소는 양식마다 10분에 한 통, 워크스페이스 전체에서 하루 다섯 통의 확인 메일을 받으며, 이미 추가된 제출은 받지 않습니다. expired는 최신 링크가 만료된 확인 대기 중인 가입을 표시합니다.