How do I prevent duplicate sends?

AI agents can sometimes retry requests due to network errors, timeouts, or logic bugs. Without safeguards, this can cause the same email to be sent multiple times. Here is how to prevent that.

Idempotent resource creation with client_id

AgentMail supports idempotency for all create operations via the clientId parameter. When you provide a clientId, AgentMail checks if a resource with that ID already exists. If it does, it returns the existing resource instead of creating a duplicate.

This works for creating inboxes, pods, webhooks, and drafts:

1
import { AgentMailClient } from "agentmail";
2
3
const client = new AgentMailClient({ apiKey: "am_..." });
4
5
// Safe to call multiple times: only creates the inbox once
6
const inbox = await client.inboxes.create({
7
  username: "support",
8
  clientId: "support-inbox-v1",
9
});
10
11
// Calling again with the same clientId returns the existing inbox
12
const sameInbox = await client.inboxes.create({
13
  username: "support",
14
  clientId: "support-inbox-v1",
15
});
16
17
// inbox.inboxId === sameInbox.inboxId

Preventing duplicate email sends

The clientId parameter is for resource creation, not for messages.send. Sends are made idempotent with an Idempotency-Key HTTP header instead.

Pass a unique key per logical send. A retry carrying the same key returns the original message and sends no second email; reusing a key with a different request (different content, inbox, or endpoint) returns 409 Conflict. Keys expire 24 hours after the send completes.

1
const key = `order-${orderId}-confirmation`; // unique per logical send, reused across retries
2
3
const message = await client.inboxes.messages.send(
4
  inbox.inboxId,
5
  { to: ["customer@example.com"], subject: "Order confirmation", text: "Your order has been confirmed." },
6
  { headers: { "Idempotency-Key": key } },
7
);

See the Idempotent Requests guide for the full semantics. The application-side patterns below still help when you want to dedupe on your own business state (e.g. “have I already replied to this thread?”).

Track sent messages with labels

Use labels to mark messages that your agent has already processed, so it does not reply twice:

1
// Before replying, check if already handled
2
const threads = await client.inboxes.threads.list(inbox.inboxId, {
3
  labels: ["unreplied"],
4
});
5
6
for (const thread of threads.threads) {
7
  const detail = await client.threads.get(thread.threadId);
8
  const lastMessage = detail.messages[detail.messages.length - 1];
9
10
  // Reply and update labels atomically in your logic
11
  await client.inboxes.messages.reply(inbox.inboxId, lastMessage.messageId, {
12
    text: "Thanks for reaching out!",
13
  });
14
15
  await client.inboxes.messages.update(inbox.inboxId, lastMessage.messageId, {
16
    addLabels: ["replied"],
17
    removeLabels: ["unreplied"],
18
  });
19
}

Use drafts for critical sends

For high-stakes emails, use drafts instead of sending directly. Create a draft, verify it has not been sent already, then send:

1
// Create a draft with a deterministic clientId
2
const draft = await client.inboxes.drafts.create(inbox.inboxId, {
3
  to: ["customer@example.com"],
4
  subject: "Order confirmation",
5
  text: "Your order has been confirmed.",
6
  html: "<p>Your order has been confirmed.</p>",
7
  clientId: "order-123-confirmation",
8
});
9
10
// Later, send the draft (only works once, draft is deleted after sending)
11
const sent = await client.inboxes.drafts.send(inbox.inboxId, draft.draftId);

Since drafts support clientId, creating the same draft multiple times is safe. And once a draft is sent, it is deleted, so calling drafts.send again will fail rather than send a duplicate.

Best practices

• Use an Idempotency-Key header on sends (messages.send, replies, forwards, drafts.send) so retries never duplicate an email
• Use clientId on all create operations (inboxes, pods, webhooks, drafts) to make them safe to retry
• Generate clientId from your business logic (e.g., order-${orderId}-confirmation), not random UUIDs
• Track state with labels to prevent your agent from processing the same message twice
• Use drafts for critical sends where duplicates would be harmful

For more details, see the Idempotent Requests guide.