# Retrieve emails

Read project-scoped email logs, recipient outcomes and the event timeline.

Source: https://docs.ravenrelay.joshlab.site/email-logs

Agent index: https://docs.ravenrelay.joshlab.site/llms.txt
OpenAPI: https://docs.ravenrelay.joshlab.site/openapi.json

## List emails

GET /v1/emails

```
curl 'https://api-production-1c6a.up.railway.app/v1/emails?status=sent&recipient=user%40example.net' \
  -H "Authorization: Bearer $RAVENRELAY_API_KEY"
```

Optional filters: status, recipient and cursor. Each page contains up to 50 records. Pass next_cursor from the response to retrieve the next page; null means there are no more records.

Response shape

```
{
  "emails": [/* email summaries */],
  "next_cursor": null
}
```

## Retrieve one email

GET /v1/emails/:id

```
curl 'https://api-production-1c6a.up.railway.app/v1/emails/YOUR_EMAIL_ID' \
  -H "Authorization: Bearer $RAVENRELAY_API_KEY"
```

The detail response includes sender, To and CC, subject, tags, metadata, providerMessageId, recipient outcomes and events. Event entries contain id, type, occurredAt and a sanitized payload. Message bodies and BCC addresses are omitted from read responses.

Use the dashboard's Emails screen for the same timeline. For multi-recipient sends, check each recipient outcome instead of treating a single delivery event as success for everyone.

## Retention and privacy

Terminal message bodies expire after seven days while worker maintenance runs. Public timelines omit original headers, BCC recipients and raw SMTP diagnostic strings. Do not place secrets in metadata.