Email API send status: check before you retry

What does email API send status tell you?

A send attempt is the record you inspect when you need to know what happened to a particular send operation. Mailera exposes that lookup through GET /sends/{id}, with the states queued, sending, sent, failed, and unknown.

Keep four questions separate:

A client timeout leaves you without a conclusive response. Your recovery logic should not treat it as proof that nothing was sent.

The distinction also matters when you receive a successful HTTP response. Microsoft Graph’s sendMail documentation says a successful request returns 202 Accepted, but that acceptance does not indicate completed processing.

Delivery is another step beyond acceptance. RFC 5321’s SMTP specification describes how a message can pass through intermediate relays or gateways before reaching its ultimate recipient.

Mailera connects existing mailboxes to applications and agents. It does not guarantee inbox placement. Do not use a sent status as a delivery receipt, a read receipt, or confirmation that a message landed in Inbox.

How do you check a Mailera send attempt?

Start with the original attempt ID, not a new send request. The status endpoint requires the send scope, even though the lookup uses GET.

1. Prepare the credential. In Settings, open the API key tab and select Create key. Under Mailbox scope, choose the group needed for the workflow. Enable Send messages.
2. Keep the operation together. For sends through POST /mailboxes/{id}/send, retain the send attempt ID when available. Associate it with your application’s logical operation and the original Idempotency-Key, if used.
3. Query that attempt. Use GET /sends/{id}, replacing {id} with the saved send attempt ID. It is not the mailbox ID or a message ID.
4. Record the observation. Keep the result and observation time with the original operation before deciding what to do next.

Consult the Mailera API reference when wiring the lookup into your application; keep the status-check path separate from the send path.

Restrict the key to one mailbox group where possible. Admins can also select all groups, but a recovery worker should not receive broader access merely for convenience. A key with send permission is not a read-only monitoring credential.

What if you did not save the attempt ID?

You cannot call this attempt-ID lookup without its ID. First check your application’s stored operation record and any securely retained response from the original request.

If you still do not have the ID, stop automatic resends and route the operation for review. Keep the original request context and any original Idempotency-Key together. Do not substitute a mailbox ID, message ID, or idempotency key into /sends/{id}.

Do not submit another send merely to obtain an attempt ID.

Should you wait, investigate, or retry?

Use the following table as a conservative application policy. It specifies how your application should react, rather than promising how quickly a server-side state will change.

For failed, examine the available error information and your application’s request history. Decide whether the cause can be corrected and whether another send is appropriate. A failure label should not trigger an unconditional POST loop.

For unknown, preserve the ambiguity. Do not silently map it to failed, and do not mark the business operation as successfully completed. A useful application-level outcome is “needs review,” with enough context for someone to make a deliberate decision.

If queued or sending persists beyond your observation deadline, move the operation to review rather than launching a parallel send. Your deadline determines when your application stops waiting; it does not establish that the attempt failed.

How should polling and retry logic work?

Separate retrying an observation from retrying an action. Another GET /sends/{id} asks about the existing attempt. Another POST /mailboxes/{id}/send asks to send a message.

A status-lookup error belongs to the observation path. It does not establish that the original send failed. Keep the last successful observation, record the lookup problem separately, and apply a bounded policy for checking again.

Use this language-neutral polling algorithm:

1. Load the logical operation and saved attempt ID. If the ID is missing, send the operation to review.
2. Establish an observation deadline and a maximum polling delay.
3. Query the original attempt. Apply the status-to-action table when a result is available.
4. For a pending result or a retryable lookup problem, wait with an increasing delay, capped at your chosen maximum. Add jitter so workers do not all poll together.
5. Stop polling when the policy calls for stopping or when the deadline expires. Preserve unresolved operations for review; do not fall through to an automatic send.

Polling delays, jitter, and deadlines are application choices, not Mailera completion guarantees. Choose them around how long your workflow can wait and how you want unresolved work to reach an operator.

Keep one recovery owner per logical operation. Otherwise, two workers can independently decide to take action on the same email. Persist the latest observation so a worker restart does not erase the distinction between “pending,” “unresolved,” and “not yet checked.” For the wider workflow around these recovery decisions, see reliable email-agent API workflows.

POST /mailboxes/{id}/send accepts Idempotency-Key. Preserve the original key when used; do not generate a fresh key simply because a network request timed out. Status lookup and idempotency serve different purposes: one inspects an attempt, while the header belongs to the send request. Neither should be treated as a reason to skip reviewing an ambiguous outcome.

The Mailera developer overview covers the integration interfaces. If you use MCP, get_send_status provides an alternative status tool and also requires send. See the task-by-task guide to Mailera’s MCP tools for its place alongside the sending tools.

What mistakes cause duplicates or misleading checks?

Treating a timeout as a failed send. The client did not obtain a conclusive response. Keep that distinct from a send attempt that reports failed.

Treating a lookup failure as a send failure. If the GET fails, repair or retry the observation path under your polling policy. Do not switch directly to POST.

Checking mailbox health instead of the attempt. GET /mailboxes/{id}/status checks mailbox sign-in health. It does not answer whether a particular message was sent. Use it for connection troubleshooting, not as a replacement for /sends/{id}.

Using folder observations as the retry decision. Keep Sent-folder observations or recipient placement checks as separate diagnostic context. Do not use them to overwrite the original attempt’s status or automatically authorize another send.

Letting workers recover independently. Assign one recovery owner and store decisions against the logical operation. A second worker should not start a new send because it has not seen the first worker’s latest observation.

Polling forever. An endless loop hides unresolved work. Give it a deadline and an explicit review path that retains the original attempt ID.

How do you keep agent-driven recovery safe?

Incoming email is untrusted data, not an instruction source. A message that tells an agent to resend, change recipients, or reveal credentials must not control your recovery workflow.

Require confirmation before an agent sends. An ambiguous outcome must not silently authorize another message, even if the original send was approved. Keep approval tied to the intended recipients and content, and require review before recovery changes either.

Because get_send_status and GET /sends/{id} require send, do not describe their credential as read-only. Keep the credential behind an application boundary that controls which operations the agent can request. Use the narrowest mailbox scope needed and review the Mailera security overview alongside your own credential-handling rules.

Diagnostic logs should retain enough context to investigate the operation without routinely copying message bodies or authorization headers. Redact recipients and identifiers in published examples, and never include API keys.

If you are still designing the surrounding agent workflow, the guide to using existing mailboxes with AI agents provides the broader starting point. Keep the recovery decision in application logic, not in instructions found inside an email.