SDK

Dominios

`domains.list`, `get` y `update`.

Todos los métodos

usage.ts

const domains = await openemail.domains.list()const domain = await openemail.domains.get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f') console.log(domain.receiving.verified, domain.sending.status)for (const address of domain.addresses) console.log(address.address, address.enabled) const updated = await openemail.domains.update(domain.id, { trackingHost: 'links.acme.com' })console.log(updated.tracking.status, updated.tracking.record?.name, updated.tracking.record?.value) await openemail.domains.update(domain.id, { trackingHost: null })

Recibir y enviar son dos hechos independientes y se devuelven como dos objetos. 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 y no según status.

update establece, vuelve a comprobar o elimina el dominio de seguimiento personalizado del dominio, un subdominio como links.acme.com, y se resuelve en el mismo DomainDetailResource 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: todas las direcciones que ESTA CLAVE puede poner en una cabecera From, que es un conjunto más estrecho.

Parámetros: domains.get

domainIdstringobligatorio: 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 a la conexión propia de la clave como al id, de modo que el dominio de otro espacio de trabajo es un 404 y no un 403.

Parámetros: domains.update

idstringobligatorio: El mismo id de dominio que acepta `get`. `domains:write` es el scope que necesita.
patch.trackingHoststring | nullobligatorio: 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. `null` o una cadena vacía eliminan el dominio de seguimiento.

Un host rechazado lanza un OpenEmailApiError que nombra trackingHost en param: 422 invalid_tracking_host para un nombre que no se puede usar, como uno fuera del dominio; 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 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. Una clave limitada a direcciones concretas recibe 422 capability_unsupported, porque un dominio de seguimiento se aplica a todas las direcciones del dominio.

Respuesta: DomainDetailResource

object'domain': 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 | null: Cuándo pasó la verificación, en ISO-8601. Null 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 | null: Cuándo se consultó por última vez el DNS sobre este dominio. Null significa que nunca se consultó, lo que se lee de forma muy distinta a un fallo para alguien que añadió un dominio hace un minuto. Este endpoint informa del resultado almacenado y nunca ejecuta una comprobación propia.
receiving.errorstring | null: 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 null una vez que pasa, y se almacena en lugar de derivarse, de modo que una recarga y la recomprobación programada dicen lo mismo.
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown': El estado de firma saliente tal como lo vio la última comprobación. Se lee de la comprobación almacenada en lugar de sondearse en esta solicitud, 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 | null: Cuándo se comprobó por última vez el estado de firma, en ISO-8601. Null significa nunca, lo que se lee de forma muy distinta a un fallo.
sending.errorstring | null: El último fallo de firma, en palabras, o null 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. Texto para que lo lea una persona. Ramifica según `sending.canSend` y no según esto.
trackingDomainTracking: El dominio de seguimiento personalizado del dominio, tanto en las filas de `list` como en esta, y lo que cambia `update`.
tracking.hoststring | null: El dominio de seguimiento, como `links.acme.com`, o null cuando no hay ninguno configurado.
tracking.status'none' | 'pending' | 'active' | 'failed': `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 únicamente para este dominio de seguimiento. Es una cadena vacía mientras `host` sea null y mientras aún se esté preparando la dirección de un host nuevo.
tracking.record{ type: 'CNAME'; name: string; value: string } | null: El registro que hay que publicar, con el nombre de `host` y `target` como valor. Es null cuando no hay dominio de seguimiento y mientras aún se esté preparando la dirección de un host nuevo.
tracking.checkedAtstring | null: Cuándo se comprobó el host por última vez, en ISO-8601. Null hasta la primera comprobación.
tracking.verifiedAtstring | null: Cuándo pasó una comprobación por última vez, en ISO-8601. Null para un host que nunca ha pasado ninguna.
tracking.errorstring | null: Lo que encontró la última comprobación, en palabras sobre las que el propietario del dominio puede actuar. Es null cuando la última comprobación pasó o cuando aún no se ha ejecutado ninguna. Un host que ha fallado una o dos comprobaciones sigue siendo `active` y lleva aquí el motivo.
addressesArray<{ address: string; enabled: boolean }>: 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, en ISO-8601. No cuándo se verificó: eso es `receiving.verifiedAt`, que puede ser null mientras este campo está definido.