Listar e obter

statusstring or array

Um estado ou vários (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`), correspondendo a qualquer um dos indicados. `bounced` significa que todos os destinatários a quem a mensagem foi enviada a devolveram, enquanto uma mensagem devolvida por alguns e que chegou aos restantes aparece como `partial`. O cliente envia um array como um único valor separado por vírgulas porque o servidor divide pelas vírgulas, e um valor fora desse conjunto dá 422 com o valor desconhecido indicado.

broadcastIdstring

Só as cópias de uma difusão, um id `brd_` vindo de `broadcasts->send`. Cada pessoa que uma difusão alcança recebe uma mensagem própria, por isso isto lista para quem foi e o que aconteceu a cada cópia. `broadcasts->listRecipients` lista as mesmas pessoas com as suas aberturas, cliques e cancelamentos de subscrição.

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.

scheduledFromDateTimeInterface or string

Apenas as mensagens agendadas para este instante ou depois. Com `scheduledTo:` e `status: ['scheduled', 'queued']` lista o que está à espera de sair numa janela de tempo, como faz o calendário da aplicação. Uma mensagem sem `scheduledAt` fica de fora. Passe um `DateTimeInterface`, enviado como instante em UTC, ou um instante ISO 8601 com o seu fuso: uma string de data sem hora é recusada por estes dois filtros.

scheduledToDateTimeInterface or string

Apenas as mensagens agendadas para este instante ou antes. Um `scheduledFrom:` posterior a `scheduledTo:` dá 422 `invalid_parameter`.

limitint

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. Em `listAll` e `iterate` é o tamanho de cada página que obtêm.

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 `invalid_cursor`.

apiKeystring

Lista com esta chave em vez da do cliente.

itemsarray

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`.

hasMorebool

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 or 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.

Cada item

objectstring

Sempre `email` numa linha desta lista.

idstring

O id próprio desta API, `msg_…`. É o que todas as outras chamadas de emails recebem e o que um cursor refere.

statusstring

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. `bounced` significa que foi devolvida por todos os destinatários depois de sair, pelo que ninguém a tem, e cada destinatário em `get` diz porquê.

modestring

`live` ou `test`, retirado da chave que a enviou. Um envio de teste é registado aqui e nunca é transmitido.

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 array, 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.

subjectstring or null

O assunto tal como foi guardado. É null numa mensagem registada sem assunto.

messageIdstring or 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 `id`.

threadIdstring or null

A conversa a que esta mensagem pertence, quando foi indicada ou atribuída. Caso contrário, null.

transportstring or null

Como os bytes saíram. É null até ao despacho. Os registos guardados ainda podem nomear transportes que já não são usados, por isso trate um valor que não conheça como informação e não como um erro.

attemptsint

Quantas tentativas de despacho a mensagem teve, 0 antes da primeira.

lastErrorstring or null

O erro de despacho mais recente, escrito para uma pessoa. É null enquanto nada tiver falhado.

scheduledAtstring or 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`.

cancellableUntilstring or 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`.

sentAtstring or 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.

tagsarray

As etiquetas indicadas no envio, devolvidas tal como vieram e nunca interpretadas. Sempre um array, vazio quando não foram definidas e nunca null, e só devolvidas: esta lista filtra por `status`, `from`, `broadcastId` e pela janela de agendamento, por isso uma etiqueta é algo que se lê numa mensagem, não uma forma de a encontrar.

broadcastIdstring or null

A difusão `brd_` de que esta mensagem é uma cópia, ou null para uma mensagem enviada sozinha.

sourcestring

Que superfície pediu o envio: `composer`, `api`, `mcp`, `ai` ou `queue`. `api` é este cliente.

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.

trackingarray

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 um `openCount` de 0 se leria como «ninguém a abriu», por isso leia-o com `?? null` em vez de presumir que a chave existe.

translationarray

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`.

O rastreio de um item

opensbool

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.

clicksbool

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.

openedbool

Indica se foi registada alguma abertura contabilizada, derivado de `openCount` ser superior a 0.

clickedbool

Indica se foi registado algum clique contabilizado, derivado de `clickCount` ser superior a 0.

openCountint

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ó.

clickCountint

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.

firstOpenAtstring or null

A primeira abertura contabilizada entre todas as cópias, e null enquanto não houver nenhuma. Os acessos automáticos nunca a alteram.