idempotencyKey in the JSON send body.
It does not use an idempotency header.
Contract
- The key is scoped to the authenticated project.
- Retrying a send with the same key returns the original send result.
- A batch item has its own
idempotencyKey; the batch wrapper does not replace item keys. - Keep the key stable for every retry of one logical message.
- Generate a new key for a genuinely new logical message.
Safe retry sequence
1
Create the key once
Persist or deterministically derive it before the first Signal request.
2
Send the request
Record the key and your internal operation ID. Do not record the API key or message body.
3
Classify the failure
Retry transient transport failures and eligible rate limits. Correct validation, authentication, permission, and domain errors first.
4
Reuse the same request identity
Send the same logical request with the original
idempotencyKey.5
Store the returned Signal ID
Follow that record through retrieval, webhooks, and your own job state.
Rate limits
For429, honor Retry-After when present and add bounded backoff with jitter.
Do not generate a new idempotency key to work around a rate limit; that changes the logical request identity and can create duplicate mail.
Indeterminate handoffs
indeterminate means Signal could not prove whether the provider accepted the handoff.
A brand-new send is unsafe because the first handoff might have succeeded.
Inspect the existing record and preserve the original admission identity instead of blindly duplicating it.
Batch retries
Keep a stable key per item and correlate the response by item index. Because the batch is admitted atomically, a failed admission queues none of its items. After a successful admission, follow each returned email ID independently rather than resubmitting the entire batch based on one later delivery failure.Idempotency guide
See request examples and integration guidance.