Emails API

Access and manage emails received by your Mailhooks domains.

List Emails

Retrieve a paginated list of emails for your account.

GET undefined/api/v1/emails

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`perPage`	integer	Items per page (default: 20, max: 100)
`from`	string	Filter by sender email
`to`	string	Filter by recipient email
`subject`	string	Filter by subject (partial match)
`filter.read`	boolean	Filter by read status (true/false)
`filter.environmentId`	string	Filter by environment ID
`filter.createdAfter`	string	Filter emails created after this ISO date
`filter.createdBefore`	string	Filter emails created before this ISO date
`sort.field`	string	Sort field (createdAt, from, subject)
`sort.order`	string	Sort order (asc, desc). Default: desc

Example Request

curl -H "x-api-key: mh_your_api_key_here" \
     "undefined/api/v1/emails?page=1&perPage=10"

Response

{
  "data": [
    {
      "id": "em_1234567890",
      "from": "[email protected]",
      "to": ["[email protected]"],
      "cc": [],
      "bcc": [],
      "subject": "Hello from Mailhooks",
      "date": "2024-01-15T10:30:00Z",
      "read": false,
      "hasAttachments": false,
      "attachments": [],
      "snippet": "This is the beginning of your email content...",
      "spfResult": "pass",
      "dkimResult": "pass",
      "dmarcResult": "pass",
      "authSummary": "SPF: pass, DKIM: pass, DMARC: pass",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "currentPage": 1,
  "perPage": 10,
  "totalItems": 150,
  "totalPages": 15,
  "hasNextPage": true
}

Response Fields

Field	Type	Description
`id`	string	Unique email identifier
`from`	string	Sender email address
`to`	string[]	Array of recipient email addresses
`cc`	string[]	Array of CC recipients
`bcc`	string[]	Array of BCC recipients
`subject`	string	Email subject line
`date`	string	Email date from headers (ISO 8601)
`read`	boolean	Whether the email has been marked as read
`hasAttachments`	boolean	Whether the email has attachments
`attachments`	object[]	Array of attachment metadata (id, filename, contentType, size)
`snippet`	string	Preview of email content (first ~100 chars)
`spfResult`	string	SPF authentication result (pass, fail, softfail, neutral, none)
`dkimResult`	string	DKIM authentication result
`dmarcResult`	string	DMARC authentication result
`authSummary`	string	Human-readable summary of auth results
`createdAt`	string	When the email was received (ISO 8601)

Get Email Details

Retrieve details for a specific email including full metadata and authentication results.

GET undefined/api/v1/emails/:id

Example Request

curl -H "x-api-key: mh_your_api_key_here" \
     "undefined/api/v1/emails/em_1234567890"

Response

{
  "id": "em_1234567890",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "cc": [],
  "bcc": [],
  "subject": "Hello from Mailhooks",
  "date": "2024-01-15T10:30:00Z",
  "read": false,
  "hasAttachments": true,
  "attachments": [
    {
      "id": "att_0987654321",
      "filename": "document.pdf",
      "contentType": "application/pdf",
      "size": 125432
    }
  ],
  "snippet": "This is the beginning of your email content...",
  "spfResult": "pass",
  "dkimResult": "pass",
  "dmarcResult": "pass",
  "authSummary": "SPF: pass, DKIM: pass, DMARC: pass",
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Email Content

Retrieve the full HTML and text content of an email.

GET undefined/api/v1/emails/:id/content

Response

{
  "html": "Your email HTML content...
 d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2">

`Mark as Read / Unread`

Update the read status of an email. This can be useful for tracking which emails have been processed.

`Mark as Read`

PATCH undefined/api/v1/emails/:id/read

`Mark as Unread`

PATCH undefined/api/v1/emails/:id/unread

`Example Request`

# Mark email as read
curl -X PATCH \
     -H "x-api-key: mh_your_api_key_here" \
     "undefined/api/v1/emails/em_1234567890/read"

# Mark email as unread
curl -X PATCH \
     -H "x-api-key: mh_your_api_key_here" \
     "undefined/api/v1/emails/em_1234567890/unread"

`Response`

{
  "id": "em_1234567890",
  "read": true,
  "updatedAt": "2024-01-15T11:00:00Z"
}

`Delete Email`

Permanently delete an email along with any attachments. Deletion removes both the database record and the stored raw email and attachment files.

DELETE undefined/api/v1/emails/:id

Usage still counts. Deleting an email does not refund it against your monthly usage quota — the email was already received and billed at ingestion time. Use delete to free up storage and clean up your inbox, not to reduce usage.

This action is irreversible. Once deleted, the email, its attachments, and the raw EML file cannot be recovered. Any webhook logs referencing the email are preserved but will no longer link to an email record.

`Example Request`

curl -X DELETE \
     -H "x-api-key: mh_your_api_key_here" \
     "undefined/api/v1/emails/em_1234567890"

`Response`

Returns 204 No Content on success, or 404 Not Found if the email does not exist or belongs to another tenant.

`Download Raw Email`

Download the original email in EML format.

GET undefined/api/v1/emails/:id/eml

Returns the raw email file with Content-Type: message/rfc822

`Download Attachment`

Download a specific attachment from an email.

GET undefined/api/v1/emails/:emailId/attachments/:attachmentId

`Example Request`

curl -H "x-api-key: mh_your_api_key_here" \
     -o attachment.pdf \
     "undefined/api/v1/emails/em_1234567890/attachments/att_0987654321"

`Email Tracking`

Each email received via SMTP is assigned a unique UUID, which is returned in the SMTP response:

250 Message accepted 87b1afa5-bdce-44c2-8a17-819cb2ac8afd

This UUID can be used to track the complete email lifecycle through SMTP reception, spam checks, and hook processing (webhooks, Discord, etc.).

For complete documentation on email tracking, lifecycle events, and querying logs by email ID, see the Email Tracking documentation.

`Response Codes`

Code	Description
200	Successful request
204	Successful request with no response body (used by delete)
400	Bad request - Invalid parameters
401	Unauthorized - Invalid API key
404	Not found - Email or attachment not found
429	Too many requests - Rate limit exceeded