Idempotência

Erros de rede e timeouts deixam você sem saber se um envio foi concluído. Uma chave de idempotência torna seguro tentar o envio de novo: se o Emailit já aceitou uma requisição com a mesma chave, ele retorna a resposta original em vez de enviar o e-mail outra vez. Esta página é a referência do cabeçalho Idempotency-Key. Para um passo a passo, consulte Envios idempotentes.

Endpoints compatíveis

Os outros endpoints ignoram o cabeçalho. Criar um domínio, uma chave de API, uma lista de contatos ou um contato já é seguro de repetir: uma segunda requisição com o mesmo nome ou e-mail retorna 409 e o objeto existing em vez de criar um duplicado.

Enviar uma chave

Adicione um cabeçalho Idempotency-Key com um valor exclusivo do e-mail que você está enviando, como um UUID ou um ID do seu próprio sistema:

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "from": "Acme <orders@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order #1042",
    "html": "<p>Thanks for your order.</p>"
  }'

const response = await fetch('https://api.emailit.com/v2/emails', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `order-${order.id}-confirmation`,
  },
  body: JSON.stringify({
    from: 'Acme <orders@acme.com>',
    to: order.email,
    subject: `Your order #${order.id}`,
    html: '<p>Thanks for your order.</p>',
  }),
});

import os
import requests

response = requests.post(
    "https://api.emailit.com/v2/emails",
    headers={
        "Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}",
        "Idempotency-Key": f"order-{order['id']}-confirmation",
    },
    json={
        "from": "Acme <orders@acme.com>",
        "to": order["email"],
        "subject": f"Your order #{order['id']}",
        "html": "<p>Thanks for your order.</p>",
    },
    timeout=30,
)

Gere a chave uma vez por e-mail, antes da primeira tentativa, e envie a mesma chave em todas as novas tentativas desse e-mail.

Como as chaves funcionam

Uma requisição reproduzida ainda passa pela autenticação e pela verificação dos limites de envio por segundo e diário, então pode retornar 401 ou 429. Os encaminhamentos também contam para o limite de encaminhamentos por hora, mesmo quando a resposta é reproduzida.

Erros

{
  "error": "Invalid Idempotency-Key"
}

{
  "error": "Idempotency key in progress",
  "message": "A request with this Idempotency-Key is already being processed. Retry shortly with the same key."
}

{
  "error": "Idempotency unavailable",
  "message": "Unable to process Idempotency-Key right now. Retry the request with the same key."
}

O Emailit nunca envia uma requisição sem a verificação de idempotência: se a chave não puder ser verificada, a requisição falha com 503 em vez de arriscar um duplicado.

Escolher boas chaves

• Derive a chave daquilo sobre o que você está notificando, como order-1042-confirmation ou password-reset-<token-id>, para que uma nova tentativa feita por outro worker ou depois de uma reinicialização use a mesma chave.
• Use um UUID novo apenas quando o e-mail não tiver um ID natural, e guarde-o com o job antes da primeira tentativa.
• Não reutilize uma chave para um e-mail diferente em menos de 24 horas. Você receberia a resposta do primeiro e-mail, e o segundo não seria enviado.

Veja também