Email Delivery Logs: Query Patterns for Developers

Email delivery logs answer a small set of questions: did the platform accept the send, which provider handled it, how many attempts were made, and where did the message stop? Start with one message ID whenever possible. Recipient-only searches get noisy quickly.

What each delivery status means

Sendmux delivery logs use four different statuses for each message.

These states describe the sending path. They don't prove inbox placement or a read. A message.delivered webhook means a recipient system accepted the message, while bounce, complaint, rejection, and delay events carry different outcomes.

Where to find delivery logs

Use the dashboard for one-off investigation. Sendmux logs show the message or log ID, date, sender, recipient, subject, status, provider, and attempt count. Filters cover an email address or message ID, status, provider, date range, and page size.

Use the Management API when the lookup needs to be repeatable. The list endpoint supports cursor pagination and accepts status, from_date, to_date, provider_id, and search filters. The search field covers sender, recipient, subject, and message ID.

Webhooks solve a different problem. They push delivery changes to your application, while logs give an operator or support process a queryable message history. Most production workflows need both.

Read the fields in the right order

A useful log entry has plenty of fields, but only four usually matter at the start.

1. ID: Use the exact message or log identifier to avoid mixing separate sends to the same recipient.

2. Status: Decide whether the message is still pending or has reached a terminal result.

3. Provider: Confirm which configured route handled the attempt.

4. Attempts: Repeated attempts can show that the message is still being retried or that one route needs closer inspection.

Sender, recipient, subject, and date help you confirm that you've found the right record. They are weaker starting keys because each can match many messages.

Query patterns that cut through noise

The order of filters matters more than the console or API you use.

Known message ID: search the exact ID, open the one record, and read status, provider, and attempts together.

Known recipient only: bound the query to the smallest useful time window, search the address, then compare subjects and senders before choosing a record.

Provider incident: filter by provider and time first, then split the results by status. A broad recipient search won't tell you whether one route is failing across many messages.

Support export: reproduce the filtered view, then export that exact result set to CSV. Sendmux applies the current filters to the export and writes formula-like values as text for safer spreadsheet use.

The same pattern appears in other systems. Google Workspace Email Log Search recommends message-level investigation and distinguishes delivery status from post-delivery mailbox state. OCI Email Delivery separates submission activity from relay, bounce, complaint, and unsubscribe activity, and supports custom-header filters in its logging query language.

A repeatable triage workflow

1. Search the message ID. If there is no matching log, check the submission request and authentication before investigating downstream delivery.

2. Read the status. A pending message and a terminal failure need different handling.

3. Confirm the provider and attempt count. This tells you which route produced the result and whether another attempt was recorded.

4. Inspect the detailed provider response or related event when available. Keep the raw response attached to the same message ID in your own incident notes.

5. Widen the query only after the single-message path is clear. Filter the same provider and time window to learn whether the failure is isolated or repeated.

This sequence prevents a common debugging mistake: starting with a broad dashboard and drawing conclusions from aggregate counts before tracing one affected message end to end.

Delivery logs and webhook events

Sendmux documents five outbound lifecycle events: message.delivered, message.bounced, message.complained, message.rejected, and message.delivery_delayed. Webhook requests include a signature, event ID, event type, and delivery-attempt header.

Verify the signature before processing the event. Dedupe on the event ID, return a 2xx response quickly, and use the delivery-attempt header for retry context. Failed webhook deliveries are retried during a 24-hour window, and recent attempt metadata plus retained payload availability can be reviewed for 7 days.

Logs remain the better surface for investigation because you can filter them after the fact. Webhooks are better for timely application behaviour, such as suppressing a bounced address or alerting on a complaint.

Query Sendmux delivery logs through the API

The Management API uses a team-scoped API key with logs.read. This request returns failed logs from a bounded UTC date range, up to 50 rows at a time:

curl "https://app.sendmux.ai/api/v1/emails/logs?status=failed&from_date=2026-08-29&to_date=2026-08-30&limit=50" \
  -H "Authorization: Bearer smx_root_your_key_here"

Follow the response cursor for the next page instead of assuming the first page is complete. For a single known record, fetch the log by its public ID and keep that ID in your application logs so support can cross-reference it later.

Retention and export

Log availability varies by provider and product. Google Workspace limits what can be found after 30 days, while OCI requires email-domain logging to be enabled and limits each log query to a 14-day range. Decide what evidence your support and audit processes need before an incident.

Export only the fields you need, keep access narrow, and avoid copying message content into a general analytics store. A long-lived incident record usually needs the message ID, timestamps, sender and recipient, status, provider, attempt count, and the relevant response or event identifier.

The practical rule

Start narrow, then widen. One message ID tells you what happened to one send. The same provider and time filters tell you whether that send is part of a larger problem.

Sendmux keeps outbound delivery logs, webhook events, and inbound mailbox workflows under one account. For developers building email into an agent or SaaS product, that shared identity makes it easier to move from a user report to the exact send, then from the exact send to the affected route.

See the Sendmux delivery log guide, Management API introduction, and webhook setup guide for the current fields and event contract.