Dominios
`domains.list`, `list_all`, `iterate`, `get` y `update`.
Todos los métodos
page = client.domains.listpage.items.each { |row| puts "#{row[:domain]} #{row.dig(:sending, :canSend)}" } domain = client.domains.get("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f")puts domain.dig(:receiving, :verified), domain.dig(:sending, :status) domain[:addresses].each do |entry| puts "#{entry[:address]} #{entry[:enabled]}"endRecibir y enviar son dos hechos independientes y se devuelven como dos Hashes. receiving.verified significa que el MX del dominio trae su correo hasta aquí y que su desafío de propiedad está publicado. sending informa de la comprobación de firma saliente: status es verified, pending, failed, no_identity o unknown, y canSend indica si ahora mismo se aceptaría un envío desde el dominio. Un veredicto negativo de más de un día se trata como desconocido y no como un rechazo, así que ramifica según canSend, que se lee con domain.dig(:sending, :canSend), y no según status.
list devuelve una OpenEmail::Page de dominios en orden alfabético, y list_all los devuelve todos en un solo Array. iterate los pasa de uno en uno a un bloque. Sin bloque devuelve un Enumerator.
domain_id = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" updated = client.domains.update(domain_id, trackingHost: "links.acme.com")puts updated.dig(:tracking, :status), updated.dig(:tracking, :record, :name), updated.dig(:tracking, :record, :value) client.domains.update(domain_id, trackingHost: nil)update establece, vuelve a comprobar o elimina el dominio de seguimiento personalizado del dominio, un subdominio como links.acme.com, y devuelve el mismo Hash que get. tracking lo informa en cada lectura. Hasta que una comprobación pase, tracking.status es pending y los enlaces con seguimiento y el píxel de apertura siguen usando el host de OpenEmail por defecto. En cuanto una pasa, es active y el correo nuevo del dominio usa el dominio de seguimiento para ambos.
get también lista las direcciones del dominio. addresses.list es la llamada relacionada: las direcciones que esta clave puede poner en una cabecera From, un conjunto más reducido, cada una con un veredicto canSend. Devuelve un OpenEmail::AddressBookPage, que las guarda en addresses en lugar de en items, junto a domains y unrestricted. Su list_all devuelve un OpenEmail::AddressBook.
app_host es un espacio de nombres propio, client.app_host. get, set, verify y delete leen y cambian la dirección de la app web del espacio de trabajo, un subdominio como mailbox.acme.com en uno de estos dominios o en cualquier otro dominio que controle el espacio de trabajo, donde su gente inicia sesión con la marca del espacio de trabajo. set devuelve los registros DNS que hay que publicar, en record y, en un dominio fuera del espacio de trabajo, en ownershipRecord. delete, y un set que sustituye una dirección, piden un código de verificación a una app OAuth: hasta que lo tenga, la llamada lanza un 403 cuyo step_up_required? es true.
branding configura esa marca. get lee los enlaces al símbolo, al logo, al logo para el modo oscuro y a la foto de acceso, las dos fuentes y el fondo de acceso. update cambia las fuentes y el fondo, upload_image(variant, data, content_type: nil) sube una de las cuatro imágenes y remove_image(variant) quita una. variant es mark, wordmark, wordmark-dark o login-background, y OpenEmail::BRAND_IMAGE_VARIANTS los nombra. data es una String binaria, un IO o un Pathname. Un Pathname como Pathname("logo.svg"), un File o un archivo subido en Rails traen su tipo consigo. Otros bytes necesitan content_type:, y una imagen sin tipo se rechaza con un 422 invalid_image. El logo es lo que pone la marca en la dirección de la app web y, con un plan de pago, en los correos que se envían para el espacio de trabajo.
Parámetros: domains.get
idStringobligatorio- El id de `domains.list`, un UUID generado cuando se añadió el dominio, no el nombre de host, así que `get("example.com")` no encuentra nada. La búsqueda está acotada tanto al espacio de trabajo propio de la clave como al id, de modo que el dominio de otro espacio de trabajo es un 404, lanzado como `OpenEmail::NotFoundError`, y no un 403. Un id nil o vacío lanza ArgumentError antes de enviar nada.
Parámetros: domains.update
idStringobligatorio- El mismo id de dominio que acepta `get`. `domains:write` es el scope que necesita.
trackingHostString or nil- Un subdominio del dominio, de 512 caracteres como máximo, como `links.acme.com`. Se recortan los espacios y se pasa a minúsculas, y se eliminan un `https://` o `http://` iniciales, una ruta y un punto final. Un valor nuevo se valida, se guarda y se comprueba en la misma llamada. Si es el valor que el dominio ya tiene, la comprobación se ejecuta de nuevo, salvo que la última fuera hace menos de 30 segundos. Pasa nil o una String vacía para eliminar el dominio de seguimiento, y omite el campo para no tocarlo.
Un host rechazado lanza un OpenEmail::ApiError que nombra trackingHost en param: un 422 invalid_tracking_host para un nombre que no se puede usar, como uno fuera del dominio, un 409 domain_not_verified para un host nuevo mientras receiving.verified sea false y el registro TXT _openemail-challenge del dominio aún no esté publicado, y un 409 tracking_host_in_use para un nombre que ya usa otro dominio, o cuando el dominio de seguimiento lo gestiona otro servidor de OpenEmail. El 422 llega como OpenEmail::ValidationError y cada 409 como OpenEmail::ConflictError. Una clave limitada a direcciones concretas recibe un 422 capability_unsupported, porque un dominio de seguimiento se aplica a todas las direcciones del dominio.
El parche son argumentos nombrados o un solo Hash, y sus campos conservan los nombres en camelCase de la API, así que tracking_host: se envía tal cual y se rechaza con un 422 unknown_parameter. update también acepta catchAll, storageHost para un dominio de archivos como files.acme.com, y dmarcPolicy. Todos los campos son opcionales y la referencia del método los cubre uno a uno. La gema reintenta update como una lectura, porque una repetición encuentra el host ya configurado y como mucho lo vuelve a comprobar.
Respuesta: un dominio (domains.get)
objectString- Siempre la cadena `domain`, tanto en las filas de `list` como en esta.
idString- El UUID del dominio. Estable durante toda la vida de la fila, y el único identificador que aceptan las demás llamadas de dominio.
domainString- El nombre de host escueto, en minúsculas: `example.com`. Único en todo el producto, un propietario por dominio, así que dos espacios de trabajo no pueden reclamarlo a la vez.
receiving.verifiedBoolean- True una vez que el DNS mostró que el MX del dominio nombra un host que trae su correo hasta aquí y, cuando la fila lleva un token de desafío, el registro TXT `_openemail-challenge` correspondiente. El MX por sí solo no demuestra nada, ya que todos los dominios para los que recibimos publican los mismos nombres de host, que es la razón de ser del token y por la que esta bandera es la condición que comprueba la entrega entrante antes de aceptar correo.
receiving.verifiedAtString or nil- Cuándo pasó la verificación, como String ISO 8601. Es nil mientras no lo haya hecho, y `verified` se deriva exactamente de esta columna, así que ambos nunca pueden contradecirse.
receiving.catchAllBoolean- Si se acepta cualquier parte local. Está activado por defecto en los dominios añadidos desde que esta pasó a ser la regla. Con él desactivado, solo se aceptan las direcciones declaradas en el dominio y el resto se rechaza en el momento SMTP, de modo que el remitente recibe un rebote en lugar de silencio.
receiving.lastCheckedAtString or nil- Cuándo se consultó el DNS por última vez sobre este dominio. Es nil cuando nunca se consultó, lo que se lee de forma muy distinta a un fallo para alguien que añadió un dominio hace un minuto. Leer un dominio no verificado vuelve a consultar el DNS cuando la última comprobación tiene más de 20 segundos, así que consultar `get` periódicamente es una forma de esperar la verificación, y `verify` comprueba de inmediato.
receiving.errorString or nil- Por qué no pasó la última comprobación, en palabras sobre las que el propietario puede actuar: `No MX records yet. DNS changes can take a few minutes to spread.` es una típica. Es nil una vez que la comprobación pasa, y se almacena en lugar de derivarse, de modo que una recarga y la recomprobación programada dicen lo mismo.
sending.statusString- El estado de firma saliente tal como lo vio la última comprobación: `verified`, `pending`, `failed`, `no_identity` o `unknown`. Se lee de la comprobación almacenada, así que `sending.checkedAt` indica qué antigüedad tiene.
sending.canSendBoolean- Si ahora mismo se aceptaría un envío desde este dominio. Un veredicto negativo de más de un día se trata como desconocido y no como un rechazo, así que esto puede ser true mientras `status` es `pending`. Ramifica según este campo antes de un envío: si es false, `emails.send` desde este dominio se rechaza con un 409 `domain_not_sendable`.
sending.checkedAtString or nil- Cuándo se comprobó por última vez el estado de firma, como String ISO 8601. Es nil cuando nunca se comprobó, lo que se lee de forma muy distinta a un fallo.
sending.errorString or nil- El último fallo de firma, en palabras, o nil una vez que pasa.
sending.noteString- Una de cinco frases, elegida según `sending.status`, que explica lo que significa ese estado en palabras sobre las que el propietario del dominio puede actuar. Es texto para que lo lea una persona, así que ramifica según `sending.canSend` y no según esto.
trackingHash- El dominio de seguimiento personalizado del dominio, tanto en las filas de `list` como en esta, y lo que cambia `update`.
tracking.hostString or nil- El dominio de seguimiento, como `links.acme.com`, o nil cuando no hay ninguno configurado.
tracking.statusString- `none` significa que no hay dominio de seguimiento configurado, `pending` que nunca ha pasado una comprobación, `active` que el correo nuevo lo usa y `failed` que pasó antes y desde entonces ha dejado de usarse. Un host activo deja de usarse tras tres comprobaciones fallidas seguidas, o cuando su última comprobación superada tiene más de 2 horas.
tracking.activeBoolean- True exactamente cuando `status` es `active`, que es cuando los enlaces con seguimiento y el píxel de apertura del correo nuevo del dominio usan el host.
tracking.targetString- La dirección a la que apunta el registro CNAME, preparada solo para este dominio de seguimiento. Es una String vacía mientras `host` es nil, y mientras la dirección de un host nuevo todavía se está preparando.
tracking.recordHash or nil- El registro que hay que publicar, un Hash con `type` (siempre `CNAME`), `name` y `value`, con el nombre de `host` y `target` como valor. Es nil cuando no hay dominio de seguimiento, y mientras la dirección de un host nuevo todavía se está preparando, así que `dig(:tracking, :record, :value)` lo lee sin riesgo.
tracking.checkedAtString or nil- Cuándo se comprobó el host por última vez, como String ISO 8601. Es nil hasta la primera comprobación.
tracking.verifiedAtString or nil- Cuándo pasó una comprobación por última vez, como String ISO 8601. Es nil para un host que nunca ha pasado ninguna.
tracking.errorString or nil- Qué encontró la última comprobación, en palabras sobre las que el propietario del dominio puede actuar. Es nil cuando la última comprobación pasó o cuando no se ha ejecutado ninguna. Un host que ha fallado una o dos comprobaciones sigue estando `active` y lleva aquí el motivo.
addressesArray<Hash>- Todas las filas de dirección del dominio, que es lo que `get` añade respecto a una fila de `list`. Incluye las filas que la propia entrega escribió bajo catch-all, y esas dejan de aceptarse en cuanto se desactiva catch-all, así que el Array no es una lista de lo que recibirá.
addresses[].addressString- La dirección completa, reconstruida a partir de la parte local almacenada y el nombre de host y pasada a minúsculas, de modo que siempre coincide con el `domain` de arriba en lugar de desviarse de él.
addresses[].enabledBoolean- False desactiva la dirección, y una dirección desactivada se rechaza incluso con catch-all activado. Todas las filas se listan igualmente, así que filtra por este campo en lugar de leer el Array como el conjunto de direcciones operativas.
createdAtString- Cuándo se añadió la fila del dominio, como String ISO 8601. No es cuándo se verificó el dominio: eso es `receiving.verifiedAt`, que puede ser nil mientras este campo está definido.