SDK

Listar y obtener

`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` y `emails.listEvents`.

emails.list

list-emails.ts

const first = await openemail.emails.list({  status: ['queued', 'scheduled'],  from: '[email protected]',  limit: 50,}) const second = first.nextCursor  ? await openemail.emails.list({ status: ['queued', 'scheduled'], limit: 50, cursor: first.nextCursor })  : null

Una página es { items, hasMore, nextCursor }. Devuelve nextCursor como cursor, con los mismos filtros, para obtener la página siguiente.

emails.iterate y emails.listAll

iterate-emails.ts

for await (const email of openemail.emails.iterate({ status: 'failed' })) {  console.error(email.id, email.lastError)} const failures = await openemail.emails.listAll({ status: 'failed', from: '[email protected]' })

Ambos siguen nextCursor por ti. iterate obtiene una página solo cuando el bucle llega a ella, así que salir del bucle detiene las solicitudes, mientras que listAll recorre todas las páginas antes de resolverse en un único array, así que dale un filtro que termine. En ambos casos es paginación por keyset, de modo que un mensaje que llegue a mitad de la iteración no puede hacer que se salte una fila, como ocurriría con un offset.

emails.get y emails.listEvents

get-email.ts

const email = await openemail.emails.get('msg_…')console.log(email.status, email.recipients) const events = await openemail.emails.listEvents('msg_…')for (const event of events) console.log(event.type, event.createdAt)

get es la única llamada que devuelve recipients, una fila por dirección. Una lista de cincuenta mensajes que llevan cada uno sus destinatarios es un informe de una página que nadie pidió.

Parámetros

statusEmailStatus | EmailStatus[]: Un estado o varios (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`), que coinciden con cualquiera de los indicados. El SDK envía un array como un único valor separado por comas porque el servidor divide por comas; un valor fuera de ese conjunto es un 422 que nombra el desconocido.
fromstring: Coincidencia exacta con la dirección de envío tal como se registró, que es el `addr@host` escueto en minúsculas. La fila se escribe con cualquier nombre visible eliminado, así que una dirección con ángulos como `Acme <[email protected]>` no coincide con nada. Tu valor se pasa a minúsculas antes de comparar, y es una igualdad, no una coincidencia por prefijo ni por dominio.
limitnumber: Filas en esta página, de 1 a 100, con 25 por defecto. Un valor fuera de ese rango se rechaza con un 422 en lugar de recortarse.
cursorstring: Un id de mensaje (`msg_…`) desde el que paginar. Es keyset y no offset: las filas vuelven estrictamente más antiguas que el `createdAt` de ese mensaje, así que los envíos que lleguen a mitad de página no pueden desplazar una fila y hacer que te la saltes. Un id que no nombra ningún mensaje de este espacio de trabajo es un 400.

Respuesta: Page<EmailResource>

itemsEmailResource[]: Una página de mensajes, de más nuevo a más antiguo por `createdAt`, extraída del sobre `data` de la API. Las filas de la lista nunca llevan el desglose `recipients` por dirección. Eso está en `get`.
hasMoreboolean: Si hay más filas que coinciden con el filtro más allá de esta página. Se responde obteniendo una fila más que `limit` en lugar de con una segunda consulta de recuento.
nextCursorstring | null: El id que hay que devolver como `cursor`, y null en la última página. `iterate` y `listAll` se detienen cuando esto es null o `hasMore` es false, ya que una página que afirme que hay más sin nombrar ningún cursor provocaría un bucle infinito.
items[].object'email': Siempre `'email'` en una fila de esta lista.
items[].idstring: El id propio de esta API, `msg_…`. Es lo que aceptan todos los demás endpoints de emails y lo que nombra un cursor.
items[].statusEmailStatus: En qué punto de su vida está el mensaje. `partial` es un estado propio y no una variante de failed: algunos destinatarios ya lo tienen y no se les puede quitar el envío, así que reintentar es un error.
items[].modeApiKeyMode: `live` o `test`, tomado de la clave que lo envió. Un envío de prueba se registra aquí y nunca se transmite.
items[].fromstring: La dirección bajo la que se autorizó el envío, almacenada escueta y en minúsculas, de modo que un nombre visible indicado en `from` sí sale por la red pero no se guarda aquí. Es una cadena simple y no un objeto porque esta es la identidad que se autorizó: una dirección fuera del alcance de envío de una clave, que no esté en un dominio que posee ni declarada en ella, se rechaza con un 403 y nunca se cambia en silencio por una que sí lo esté.
items[].subjectstring | null: El asunto tal como está almacenado. Null en un mensaje registrado sin ninguno.
items[].messageIdstring | null: El Message-ID de RFC 5322, no nuestro id. Null hasta que existe el MIME, y el servicio de envío lo reescribe a la salida, así que un rebote o DSN posterior lleva un id distinto y se correlaciona mediante `items[].id`.
items[].threadIdstring | null: El hilo al que pertenece este mensaje, cuando se indicó o se asignó uno. Null en caso contrario.
items[].transportEmailTransport | (string & {}) | null: Cómo salieron los bytes. Null hasta el despacho, y con tipo abierto para que un transporte que este SDK aún no nombra no sea un cambio incompatible: los registros almacenados pueden seguir nombrando algunos que ya no se usan.
items[].attemptsnumber: Cuántos intentos de despacho ha tenido el mensaje, 0 antes del primero.
items[].lastErrorstring | null: El error de despacho más reciente, escrito para una persona. Null mientras no haya fallado nada.
items[].scheduledAtstring | null: Cuándo está previsto que salga el mensaje, como instante ISO-8601. Solo es null en un envío inmediato sin ventana de cancelación: una ventana es un retraso corto y nada más, así que `cancellableForSeconds` también rellena este campo, en una fila cuyo `status` es `queued` y no `scheduled`.
items[].cancellableUntilstring | null: El instante en que está previsto que salga el mensaje, con el mismo valor que `scheduledAt` en cualquier envío que se aplazara y null en uno que no. Es una marca de tiempo para mostrar, no la comprobación que hace el servidor: `cancel` ramifica según `status` y solo detiene un mensaje mientras siga en `queued` o `scheduled`.
items[].sentAtstring | null: Cuándo salió. Null hasta que el despacho se ha completado, razón por la cual el campo por el que hay que ramificar es `status` y no este.
items[].tagsRecord<string, string>: Las etiquetas indicadas en el envío, devueltas tal cual y nunca interpretadas. Siempre un objeto (`{}` cuando no se estableció ninguna, nunca null), y solo devueltas: este endpoint filtra por `status` y `from`, así que una etiqueta es algo que se lee de un mensaje y no una forma de encontrarlo.
items[].sourceEmailSource: Qué superficie solicitó el envío: `composer`, `api`, `mcp`, `ai` o `queue`. `api` es este cliente.
items[].createdAtstring: Cuándo se escribió el registro de envío, que es antes del despacho. Es el campo por el que ordena la lista y el campo con el que compara un cursor.
items[].trackingEmailTrackingSummary: El resumen de interacción, presente solo en una fila cuyo mensaje tuvo seguimiento y ausente en caso contrario. Su ausencia es la respuesta a «¿se hizo seguimiento de esto?», mientras que `openCount: 0` se leería como «nadie lo abrió».
items[].tracking.opensboolean: Si este mensaje salió con un píxel. Lo que se aplicó a este mensaje, no lo que dice ahora la configuración de la cuenta.
items[].tracking.clicksboolean: Si se reescribieron los enlaces de este mensaje. False cuando el cuerpo no tenía enlaces que reescribir, ya que entonces no se cambió nada.
items[].tracking.openedboolean: Si se registró alguna apertura contabilizada, derivado de `openCount > 0`.
items[].tracking.clickedboolean: Si se registró algún clic contabilizado, derivado de `clickCount > 0`.
items[].tracking.openCountnumber: Aperturas que se cree causadas por una persona, sumadas sobre cada copia del mensaje. Los escáneres y los proxies de privacidad se registran pero se excluyen, y las peticiones repetidas en menos de treinta segundos se agrupan en una.
items[].tracking.clickCountnumber: Clics contabilizados, sumados sobre las copias. Se deduplican por enlace y no por mensaje, porque seguir dos enlaces con segundos de diferencia son dos actos y no una repetición.
items[].tracking.firstOpenAtstring | null: La primera apertura contabilizada entre las copias, y null mientras no haya ninguna. Las visitas de máquinas nunca la mueven.
items[].translationEmailTranslationResource: Nunca está presente en una fila de lista: el registro de traducción vive en la solicitud almacenada, que una lista deliberadamente no obtiene. Su ausencia aquí no dice nada sobre si el mensaje se tradujo. Pregúntale a `get`.