Emails API

Access and manage emails received by your Mailhooks domains.

List Emails

Retrieve a paginated list of emails for your account.

GET http://localhost:3000/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)

Example Request

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

Response

{
  "data": [
    {
      "id": "em_1234567890",
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subject": "Hello from Mailhooks",
      "date": "2024-01-15T10:30:00Z",
      "hasAttachments": false,
      "snippet": "This is the beginning of your email content..."
    }
  ],
  "currentPage": 1,
  "perPage": 10,
  "totalItems": 150,
  "totalPages": 15,
  "hasNextPage": true
}

Get Email Details

Retrieve details for a specific email.

GET http://localhost:3000/api/v1/emails/:id

Example Request

curl -H "x-api-key: mh_your_api_key_here" \
     "http://localhost:3000/api/v1/emails/em_1234567890"

Get Email Content

Retrieve the full HTML and text content of an email.

GET http://localhost:3000/api/v1/emails/:id/content

Response

{
  "html": "<html><body><p>Your email HTML content...</p></body></html>",
  "text": "Your email plain text content..."
}

Download Raw Email

Download the original email in EML format.

GET http://localhost:3000/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 http://localhost:3000/api/v1/emails/:emailId/attachments/:attachmentId

Example Request

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

Response Codes

Code	Description
200	Successful request
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