Skip to Content
Docs
Guides

Message activity

Look up delivery status per message, filter by tags, and read events.

Message activity is the read-only log of everything you've sent: status, recipients, tags, and timing — newest first.

In the console

Open Dashboard → Activity. The tiles count messages by status; below them, search by recipient, subject, or message id, and filter by status or sending domain. Click a message to open its delivery timeline.

The Activity view in the emitd console: status tiles above a searchable list of messages

Listing

curl "https://api.emitd.com/v1/messages?limit=25" \
  -H "Authorization: Bearer $EMITD_API_KEY"
  • ?limit= — default 25, max 100
  • ?cursor= — a bare epoch-millisecond created_at from the previous page; returns rows strictly older
  • ?tag_key=campaign&tag_value=welcome — filter on the tags JSON column (tag_value alone is ignored). There is no status filter on this endpoint.
{
  "data": [
    {
      "id": "msg_2h8Kd0Rk9Qa",
      "from_addr": "hello@yourdomain.com",
      "to_addr": "ada@lovelace.io",
      "subject": "Your receipt #4021",
      "status": "sent",
      "ses_message_id": "0100018f...",
      "error": null,
      "created_at": 1783386190000,
      "updated_at": 1783386190864
    }
  ],
  "next_cursor": 1783386190000
}

Status is one of queued, sent, failed, suppressed, scheduled, cancelled. Note to_addr is the primary recipient only — the full recipient set isn't stored on this row.

Detail

GET /v1/messages/{id} returns the full record for one message (404 if it doesn't exist or isn't yours — the API never distinguishes the two).

Find out why an email didn't arrive

Every message comes with a diagnosis: what happened, and what to do next.

{
  "state": "bounced",
  "summary": "The recipient's mail server rejected it permanently, so we've stopped sending to this address.",
  "next_step": "Check the address for a typo, and ask for a correct one. Sending to a dead address again hurts your domain's reputation."
}

In the console, it's at the top of a message's details. next_step is null when there's nothing to do.

When someone says they didn't get an email, you usually have their address but no message ID. POST /v1/diagnose starts from the address:

curl https://api.emitd.com/v1/diagnose \
  -H "Authorization: Bearer $EMITD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com"}'

It reads your suppression list and your 5 latest messages to that address, and returns suppressed, messages, and a diagnosis for the latest one. The address goes in the body so it stays out of URLs and API logs. Through MCP, the same lookup is the diagnose_delivery tool.

stateMeaning
deliveredThe recipient's mail server accepted it. It can still land in spam.
bouncedRejected permanently. The address is now suppressed.
temporary_bounceRefused for now, often a full mailbox. The address isn't blocked.
complainedThe recipient marked it as spam. The address is now suppressed.
suppressedNot sent, because the address is blocked. summary says why.
failedCouldn't be sent. next_step says how to fix it.
sendingOn its way. Allow up to 15 minutes.
delayedSent, but not accepted yet. Wait before resending, or the recipient may get it twice.
unconfirmedSent, with no report back after 24 hours.
stuckIn the queue for over 15 minutes. Contact support.
scheduled, held, cancelledWaiting for its send time, waiting for approval, or cancelled.
not_sentNo record of mail to this address (POST /v1/diagnose only).

Events

Delivery, bounce, complaint, open, and click events are joined to messages and streamed to your webhooks. Simulated events from test mode live at GET /v1/email/test-events.

API request logs

Activity shows what happened to each message. Developers → Logs shows every call your integration made to the emitd API: the method and path, the response status, how long it took, which API key and client made it, and its request ID. Search by path, method, request ID or key, or filter by status, to find the failing call.

The Logs screen: API requests with their status, method and path, duration, request ID and time

Every API response carries the same ID in its X-Request-Id header. Quote it when you contact support and we can find the exact request.

Read the same list from your own code or an agent. status takes ok, error or a code like 422, and searches the last 7 days:

curl "https://api.emitd.com/v1/logs?status=error&limit=20" \
  -H "Authorization: Bearer $EMITD_API_KEY"

Calls are kept for 90 days, with no request or response bodies. Reading /v1/logs isn't logged, so polling it doesn't fill your history.

Filtering patterns

# all messages tagged campaign=welcome, one page
curl "https://api.emitd.com/v1/messages?tag_key=campaign&tag_value=welcome&limit=100" \
  -H "Authorization: Bearer $EMITD_API_KEY"

Tag every send at the source (tags: { "campaign": "welcome" }) — tags are written once at send time and are what both activity filtering and analytics hang off.

On this page