​
What is idempotency?

Idempotency ensures that retrying a request (due to network issues, timeouts, etc.) will not result in duplicate emails.

​
Usage

  • Header: Idempotency-Key
  • Type: Any unique string (UUID v4 recommended)
  • Scope: Each unique key + request body is valid for 24 hours

​
How it works

  • If you send the same request with the same Idempotency-Key within 24 hours, you’ll get the same response and no duplicate email is sent.
  • If you send a different request body with the same key, you’ll get a 422 error.

​
Examples

​
Send an email

curl -X POST https://api.lettermint.co/v1/send \
-H "x-lettermint-token: $TOKEN" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-d '{
"from": "John Doe <john@yourdomain.com>",
"to": ["recipient@example.com"],
"subject": "Hello from Lettermint!",
"text": "Hello! This is a test email."
}'

​
Retry with the same key and body

If you retry the exact same request, you will receive a 202 Accepted with the same message_id and no duplicate email will be sent.

​
Conflict with same key, different body

curl -X POST https://api.lettermint.co/v1/send \
    -H "x-lettermint-token: $TOKEN" \
    -H "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000" \
    -H "Content-Type: application/json" \
    -d '{
    "from": "John Doe <john@yourdomain.com>",
    "to": ["recipient@example.com"],
    "subject": "This is different!",
    "text": "Thanks for signing up."
}'

Executing the above calls after the first example will result in a 422 Unprocessable Entity response with:

{
    "message": "This idempotency key has already been used on a request with a different payload. Retrying this request requires changing the idempotency key or payload."
}

​
SMTP

If you need idempotency but are using the SMTP relay, you can simply add the header to the SMTP request and we’ll handle the request similar to the API.

​
Example

You can use the following example for nodemailer:

    await transporter.sendMail({
      from: 'sender@yourdomain.com',
      to: 'recipient@example.com',
      subject: 'Test Email',
      text: 'Hello! This is a test email.',
      html: '<h1>Hello!</h1><p>This is a test email.</p>',
      headers: {
        "Idempotency-Key": "123e4567-e89b-12d3-a456-426614174000"
      }
    });

​
Recommendations

  • Always set Idempotency-Key when retries are possible.
  • Generate a new key for each unique email.
  • Store the key if you need to retry the same request.
  • Do not reuse keys for different emails.

Summary: Add the Idempotency-Key header to your /send requests to prevent duplicate emails when retrying. Use a unique key per email. Identical key + body will be safe to retry; identical key + different body results in an error error.