SDK
Agendar e cancelar
`scheduledAt`, `emails.reschedule` e `emails.cancel`.
Enviar mais tarde
await openemail.emails.send({ ...message, scheduledAt: 'PT1H' })await openemail.emails.send({ ...message, scheduledAt: new Date('2027-01-01T09:00:00Z') })await openemail.emails.send({ ...message, scheduledAt: '2027-01-01T09:00:00.000Z' })Um Date, um instante ISO-8601 ou uma duração como PT1H / P2D. Até um ano à frente, nunca no passado.
Mover e interromper
const queued = await openemail.emails.send({ ...message, scheduledAt: 'PT1H' }) await openemail.emails.reschedule(queued.id, new Date(Date.now() + 86_400_000))await openemail.emails.cancel(queued.id)Só as mensagens queued e scheduled podem ser interrompidas; qualquer uma mais avançada dá conflict_error, porque parte dela já está na caixa de correio de alguém. Cancelar uma mensagem já cancelada é bem-sucedido e não altera nada.
Em alternativa, uma janela para anular
await openemail.emails.send({ ...message, cancellableForSeconds: 30 })Uma mensagem agendada já pode ser cancelada até sair, pelo que as duas opções não podem ser combinadas e o servidor recusa-o. Use esta para uma janela de anulação do envio numa mensagem imediata.
Parâmetros: agendamento
scheduledAtDate | string- Quando enviar, em `emails.send`: um `Date`, um instante ISO-8601 ou uma duração como `PT1H` ou `P2D`, que o cliente converte numa string para envio. Pelo menos um segundo no futuro e no máximo 365 dias à frente, sendo a violação de qualquer um dos limites um `validation_error` em `scheduledAt`, e não é aceite linguagem natural, porque interpretar mal "próxima terça-feira" envia uma mensagem num momento que não pode ser desfeito.
cancellableForSecondsnumber- Uma janela de anulação do envio num envio IMEDIATO: um inteiro de 0 a 900, com 0 por predefinição. Qualquer valor acima de 0 é recusado em conjunto com `scheduledAt`, que já pode ser cancelado até sair, e uma mensagem retida desta forma fica em `queued` e não em `scheduled`. É o mesmo mecanismo de diferimento com um atraso curto.
idstringobrigatório- O id `msg_…`, e o primeiro argumento tanto de `emails.cancel` como de `emails.reschedule`. Ambos exigem `emails:send` e não um âmbito próprio, e ambos são resolvidos dentro do espaço de trabalho da própria chave, pelo que um id que pertença a outro dá `not_found_error`, exatamente como um id que nunca existiu.
reschedule.scheduledAtDate | stringobrigatório- A nova hora, como segundo argumento de `emails.reschedule`, interpretada pelas mesmas regras e dentro da mesma janela de um ano, e a única coisa que o `PATCH /emails/{id}` subjacente vai alterar. Uma duração é relativa ao momento em que o SERVIDOR a lê, pelo que um reagendamento repetido fica ligeiramente mais tarde do que o primeiro teria ficado: mais tarde, nunca mais cedo.
Resposta: EmailResource
object'email'- Sempre `email`. Ambas as chamadas respondem com a mensagem completa e não com uma confirmação, pelo que não é preciso voltar a obter nada para ver o que mudou; `emails.send` devolve esta mesma forma mais `replayed`.
idstring- O identificador `msg_…`. Estável durante toda a vida da mensagem e o id que todas as outras chamadas sobre ela recebem.
statusEmailStatus- `cancelled` após um cancelamento e `scheduled` após um reagendamento, incluindo numa mensagem que estava apenas `queued` atrás de uma janela para anular, que um reagendamento transforma num agendamento real. Só as mensagens `queued` e `scheduled` podem ser movidas ou interrompidas; qualquer uma mais avançada dá `conflict_error` com o código `email_not_cancellable`, porque parte dela já está na caixa de correio de alguém.
scheduledAtstring | null- O instante ISO em que a mensagem deve ser despachada. Definido tanto para uma janela para anular como para um envio com `scheduledAt`, já que os dois são um único mecanismo, e null num envio imediato simples.
cancellableUntilstring | null- Quando o cancelamento deixa de funcionar, que é o mesmo instante que `scheduledAt` em ambos os percursos diferidos. É null num envio imediato, que já saiu quando a chamada retorna.
sentAtstring | null- Quando a mensagem saiu efetivamente. É null enquanto espera, e null para sempre numa mensagem cancelada.
messageIdstring | null- O Message-ID do RFC 5322, null até o MIME existir, pelo que é sempre null numa mensagem sobre a qual estas duas chamadas podem agir. Não serve para referenciar a mensagem na API, nem é aquilo com que uma devolução posterior regressa: o serviço de envio reescreve o cabeçalho à saída.
threadIdstring | null- A conversa a que esta mensagem pertence, retirada do pedido e reescrita com o que o transporte reportar depois de enviar. É null quando não é uma resposta.
transportEmailTransport | (string & {}) | null- Como os bytes saíram, e null até ao despacho, pelo que é null em todas as mensagens que um cancelamento ou um reagendamento podem devolver. Um envio em modo de teste regista `test`, e a união permanece aberta para que um transporte que este SDK ainda não nomeia não seja uma alteração incompatível.
attemptsnumber- Quantas vezes o despacho reservou esta linha. É incrementado pela reserva e não por um envio bem-sucedido, e é 0 para tudo o que ainda está à espera.
lastErrorstring | null- A última falha registada na mensagem, null enquanto nada tiver falhado. Um envio diferido cuja tarefa não pôde ser colocada em fila é registado aqui como `Could not schedule: …` e passa a `failed`, que é a única forma de uma mensagem agendada deixar de poder ser cancelada sem que ninguém o peça.
fromstring- O endereço com que a mensagem foi autorizada a sair, guardado simples e em minúsculas. Nem sempre é o endereço pedido (uma chave restrita que não indica `from` resolve para o primeiro endereço que pode usar), e qualquer nome de apresentação é descartado aqui, porque o filtro `from` de `emails.list` compara por igualdade.