SDK

Listar e obter

`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` e `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

Uma página é { items, hasMore, nextCursor }. Passe nextCursor de volta como cursor, com os mesmos filtros, para obter a página seguinte.

emails.iterate e 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 seguem nextCursor por si. iterate só obtém uma página quando o ciclo lá chega, pelo que sair do ciclo interrompe os pedidos, enquanto listAll percorre todas as páginas antes de resolver para um único array, por isso dê-lhe um filtro que termine. Em ambos os casos a paginação é por keyset, pelo que uma mensagem que chegue a meio da iteração não pode fazer saltar uma linha como aconteceria com um offset.

emails.get e 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 é a única chamada que devolve recipients, uma linha por endereço. Uma lista de cinquenta mensagens, cada uma com os seus destinatários, seria uma página de relatório que ninguém pediu.

Parâmetros

statusEmailStatus | EmailStatus[]: Um estado ou vários (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`), correspondendo a qualquer um dos indicados. O SDK envia um array como um único valor separado por vírgulas porque o servidor divide pelas vírgulas; um valor fora desse conjunto dá 422 com o valor desconhecido indicado.
fromstring: Correspondência exata com o endereço de envio tal como foi registado, que é o `addr@host` simples em minúsculas. A linha é escrita sem qualquer nome de apresentação, pelo que um angle-addr como `Acme <[email protected]>` não corresponde a nada. O seu valor é convertido para minúsculas antes da comparação, e é uma igualdade e não uma correspondência por prefixo ou por domínio.
limitnumber: Linhas nesta página, de 1 a 100, com 25 por predefinição. Um valor fora desse intervalo é recusado com 422 em vez de ser ajustado ao limite.
cursorstring: Um id de mensagem (`msg_…`) a partir do qual paginar. Keyset em vez de offset: as linhas devolvidas são estritamente mais antigas do que o `createdAt` dessa mensagem, pelo que envios que cheguem a meio da página não podem fazer-lhe perder uma linha. Um id que não corresponda a nenhuma mensagem neste espaço de trabalho dá 400.

Resposta: Page<EmailResource>

itemsEmailResource[]: Uma página de mensagens, das mais recentes para as mais antigas por `createdAt`, extraída do envelope `data` da API. As linhas da lista nunca incluem a discriminação `recipients` por endereço. Essa está em `get`.
hasMoreboolean: Indica se há mais linhas que correspondem ao filtro para além desta página. Determinado obtendo uma linha a mais do que `limit`, em vez de uma segunda consulta de contagem.
nextCursorstring | null: O id a passar de volta como `cursor`, e null na última página. `iterate` e `listAll` param quando este é null ou `hasMore` é false, já que uma página que indicasse haver mais sem nomear nenhum cursor ficaria em ciclo infinito.
items[].object'email': Sempre `'email'` numa linha desta lista.
items[].idstring: O id próprio desta API, `msg_…`. É o que todos os outros endpoints de emails recebem e o que um cursor refere.
items[].statusEmailStatus: Em que fase da sua vida está a mensagem. `partial` é um estado próprio e não uma variante de falha: alguns destinatários já a têm e não é possível anular o envio, pelo que tentar de novo é errado.
items[].modeApiKeyMode: `live` ou `test`, retirado da chave que a enviou. Um envio de teste é registado aqui e nunca é transmitido.
items[].fromstring: O endereço com que o envio foi autorizado, guardado simples e em minúsculas, pelo que um nome de apresentação indicado em `from` continua a ser enviado mas não é guardado aqui. Uma string simples e não um objeto, porque esta é a identidade que foi autorizada: um endereço fora do âmbito de envio de uma chave, que não esteja num domínio que ela detém nem nomeado nela, é recusado com 403, e nunca é trocado silenciosamente por um que esteja.
items[].subjectstring | null: O assunto tal como foi guardado. É null numa mensagem registada sem assunto.
items[].messageIdstring | null: O Message-ID do RFC 5322, e não o nosso id. É null até o MIME existir, e é reescrito pelo serviço de envio à saída, pelo que uma devolução ou DSN posterior traz um id diferente e a correlação faz-se por `items[].id`.
items[].threadIdstring | null: A conversa a que esta mensagem pertence, quando foi indicada ou atribuída. Caso contrário, null.
items[].transportEmailTransport | (string & {}) | null: Como os bytes saíram. É null até ao despacho, e o tipo é aberto para que um transporte que este SDK ainda não nomeia não seja uma alteração incompatível: os registos guardados podem ainda nomear transportes que já não são usados.
items[].attemptsnumber: Quantas tentativas de despacho a mensagem teve, 0 antes da primeira.
items[].lastErrorstring | null: O erro de despacho mais recente, escrito para uma pessoa. É null enquanto nada tiver falhado.
items[].scheduledAtstring | null: Quando a mensagem deve sair, como instante ISO-8601. É null apenas num envio imediato sem janela de cancelamento: uma janela é um pequeno atraso e nada mais, pelo que `cancellableForSeconds` também preenche este campo, numa linha cujo `status` é `queued` e não `scheduled`.
items[].cancellableUntilstring | null: O instante em que a mensagem deve sair, com o mesmo valor que `scheduledAt` em qualquer envio diferido e null num que não o foi. É uma marca temporal para mostrar e não o critério que o servidor usa: `cancel` decide com base em `status`, e só interrompe uma mensagem enquanto ainda está `queued` ou `scheduled`.
items[].sentAtstring | null: Quando saiu. É null até o despacho estar concluído, e é por isso que `status`, e não este, é o campo em que basear a lógica.
items[].tagsRecord<string, string>: As etiquetas fornecidas no envio, devolvidas e nunca interpretadas. Sempre um objeto (`{}` quando não foi definida nenhuma, nunca null), e apenas devolvidas: este endpoint filtra por `status` e `from`, pelo que uma etiqueta é algo a ler numa mensagem e não uma forma de a encontrar.
items[].sourceEmailSource: Que superfície pediu o envio: `composer`, `api`, `mcp`, `ai` ou `queue`. `api` é este cliente.
items[].createdAtstring: Quando o registo de envio foi escrito, o que acontece antes do despacho. É o campo pelo qual a lista é ordenada e o campo com que um cursor é comparado.
items[].trackingEmailTrackingSummary: O resumo de envolvimento, presente apenas numa linha cuja mensagem foi rastreada e ausente nos restantes casos. A ausência é a resposta a "isto foi rastreado?", enquanto `openCount: 0` se leria como "ninguém a abriu".
items[].tracking.opensboolean: Indica se esta mensagem saiu com um píxel. O que foi aplicado a esta mensagem, e não o que a definição da conta diz agora.
items[].tracking.clicksboolean: Indica se as ligações desta mensagem foram reescritas. É false quando o corpo não tinha ligações a reescrever, já que nesse caso nada foi alterado.
items[].tracking.openedboolean: Indica se foi registada alguma abertura contabilizada, derivado de `openCount > 0`.
items[].tracking.clickedboolean: Indica se foi registado algum clique contabilizado, derivado de `clickCount > 0`.
items[].tracking.openCountnumber: Aberturas que se considera terem sido feitas por uma pessoa, somadas em todas as cópias da mensagem. Scanners e proxies de privacidade são registados mas excluídos, e pedidos repetidos num intervalo de trinta segundos contam como um só.
items[].tracking.clickCountnumber: Cliques contabilizados, somados em todas as cópias. Os duplicados são eliminados por ligação e não por mensagem, porque seguir duas ligações com segundos de diferença são dois atos e não uma repetição.
items[].tracking.firstOpenAtstring | null: A primeira abertura contabilizada entre todas as cópias, e null enquanto não houver nenhuma. Os acessos automáticos nunca a alteram.
items[].translationEmailTranslationResource: Nunca está presente numa linha de lista: o registo da tradução está no pedido guardado, que uma lista deliberadamente não obtém. A sua ausência aqui não diz nada sobre se a mensagem foi traduzida. Consulte `get`.