Formularios
`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` y `subscribe`.
Todos los métodos
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.sizeUn formulario guarda un borrador document y el publishedDocument que ven los visitantes. update cambia el borrador y los ajustes, y publish activa el borrador. Los ajustes surten efecto al instante, esté publicado o no, y expectedUpdatedAt rechaza con un 409 version_conflict, lanzado como OpenEmail::ConflictError, un guardado que sobrescribiría el de otra persona.
Los campos de un formulario conservan los nombres en camelCase de la API (expectedUpdatedAt:, doubleOptIn), pasados como argumentos nombrados o como un solo Hash, mientras que los filtros y las opciones son argumentos nombrados en snake_case (status: en list_submissions, offset_minutes: en analytics). Un formulario vuelve como un Hash con claves Symbol, así que form[:subscribeUrl] lee la dirección que recibe las suscripciones.
Leer requiere forms:read y cambiar requiere forms:write. approve_submission también requiere contacts:write, porque añade un contacto. resend_confirmation también requiere emails:send, igual que una llamada que haga que el formulario envíe correo: activar doubleOptIn, configurar senderAddress o el correo de confirmación, o publicar o reanudar un formulario con doble opt-in. delete pide un código de verificación a un token de acceso OAuth, y a una clave de API nunca. Hasta que el token tenga uno, delete lanza OpenEmail::PermissionError con step_up_required? a true.
subscribe suscribe a alguien como lo hace la página del formulario y no envía ninguna credencial, ni siquiera desde un cliente que tenga una, así que api_key: se ignora. Las respuestas se pasan como argumentos nombrados o como un solo Hash, con las claves de los campos del formulario. Todas las suscripciones desde una misma red comparten un límite de 40 cada diez minutos, así que un servidor que reenvía suscripciones de muchas personas lo alcanza enseguida: en su lugar, añade a las personas que ya conoces con audiences.import_contacts. Pasado el límite, la llamada lanza OpenEmail::RateLimitError. Pasa la página en la que estaba el formulario como oe_source:, omite oe_started y envía oe_website vacío o no lo envíes.
Un 422 de subscribe es invalid_form_submission, lanzado como OpenEmail::ValidationError, y el fields del error lista cada respuesta que falta o no es válida como un Hash con key y error, con motivos como required, email y option. OpenEmail::FORM_FIELD_ERRORS nombra todos los motivos. La gema se ejecuta en un servidor. Un navegador envía él mismo las respuestas al subscribeUrl del formulario, como cuerpo JSON o con una cabecera Accept: application/json, y recibe JSON de vuelta desde cualquier origen. Sin ninguna de las dos cosas, recibe una redirección 303 a la página alojada.
Respuesta: un formulario
list devuelve una OpenEmail::Page de formularios, del más reciente al más antiguo, sin document ni settings, y list_all e iterate recorren todas las páginas. get, create, update, publish, pause, resume y duplicate devuelven el formulario completo como un Hash, que añade document, publishedDocument, settings, audiences, senderIssue y senderProblem.
idString- El identificador duradero, `frm_` seguido de 24 caracteres hexadecimales.
statusString- `draft` hasta la primera publicación, luego `live` mientras acepta suscripciones y `paused` mientras no las acepta. Un formulario nunca vuelve a `draft`. `OpenEmail::FORM_STATUSES` nombra los tres.
urlString- La página alojada del formulario publicado, para compartirla como enlace.
subscribeUrlString- Adónde envían las respuestas un formulario HTML simple o un script en el navegador.
documentHash- El borrador: los `fields` en orden, los textos de `copy` que los rodean y el `style`.
publishedDocumentHash or nil- Lo que ven ahora los visitantes, o nil hasta la primera publicación.
settingsHash- Adónde van las suscripciones y qué pasa después de cada una: `audienceIds`, `doubleOptIn`, `senderAddress`, el correo de confirmación, `successAction`, `redirectUrl` y `notifyAddresses`.
hasUnpublishedChangesBoolean- True cuando el borrador difiere de lo que ven los visitantes. Siempre false antes de la primera publicación.
senderIssueString or nil- Por qué un formulario con doble opt-in no puede enviar sus correos de confirmación ahora mismo: `missing`, `not_sendable` o `not_allowed`. Es nil cuando puede. `OpenEmail::FORM_SENDER_ISSUES` nombra los tres.
statsHash- `views`, `submissions`, `added`, `pending` y `lastSubmittedAt`, contados en el momento de la lectura.
Envíos
list_submissions devuelve páginas del más reciente al más antiguo, con q: para buscar en las direcciones de correo y status: para pending o added, y list_all_submissions e iterate_submissions recorren todas las páginas. OpenEmail::FORM_SUBMISSION_STATUSES nombra los dos estados. Cada envío es un Hash que guarda las respuestas tal como se enviaron, etiquetas incluidas, así que se sigue leyendo bien después de que cambie el formulario.
resend_confirmation devuelve el envío con confirmationSent. Es false cuando no salió nada: una dirección recibe una confirmación por formulario cada diez minutos y cinco al día en todo el espacio de trabajo, y un envío ya añadido no recibe ninguna. expired marca una suscripción pendiente cuyo último enlace ha caducado.