> For the complete documentation index, see [llms.txt](https://docs.hostinger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostinger.com/emails/mail-api.md).

# Mail API

Read, search, send and organise mail in your Hostinger Email mailboxes over HTTPS. Authentication, request and response format, and every Mail API endpoint.

The Mail API works with the contents of the mailboxes on your [Hostinger Email](/emails/overview.md) plan: list and search messages, read and move them, send mail, manage folders, check quota, and subscribe to mailbox events with webhooks. It's the API behind [Agentic Mail](/emails/agentic-mail.md), the [Email SDKs](/api-reference/email-sdks.md), the `hostinger-mail` CLI, and the email MCP server.

Every endpoint page in this section is rendered from the [Mail API OpenAPI specification](https://api.mail.hostinger.com/openapi/openapi.json), so parameters, schemas and responses always match the live API.

> **Note:** The Mail API is separate from the [Hostinger API](/api-reference/overview.md) at developers.hostinger.com. It has its own base URL and its own tokens, and the two don't accept each other's tokens. The Hostinger API's [Mail endpoints](/api-reference/endpoints/mail.md) set up the email service itself — orders, mailboxes, aliases, forwarders, and the tokens for this API. Use the Mail API to work with what's inside a mailbox.

## Authentication

1. Create a token under **Agentic Mail** → **API access** in your email domain's sidebar. [Agentic Mail](/emails/agentic-mail.md#api-access) covers the steps and the permissions you can give it.
2. Send it as a bearer header on every request:

```bash
curl https://api.mail.hostinger.com/api/v1/me \
  -H "Authorization: Bearer YOUR_MAIL_API_TOKEN"
```

A token belongs to a single email order. It can reach every mailbox in that order, or only the mailboxes you picked when you created it. Tokens from [hPanel → API](https://hpanel.hostinger.com/profile/api) don't work here.

## Making requests

The base URL is `https://api.mail.hostinger.com`, and every path starts with `/api/v1/`.

Start with [Get the authenticated account](/emails/mail-api/account/get-the-authenticated-account.md). It returns the mailboxes your token can manage, and every other endpoint takes one of their resource IDs as `{mailboxResourceId}`. Endpoints that work on messages also take a `{folder}`, such as `INBOX`. URL-encode folder paths that contain `/` or spaces.

Send request bodies as JSON with `Content-Type: application/json`.

## Responses

Every response except `204 No Content` wraps its payload in a `data` field:

```json
{
  "data": {
    "resourceId": "AC1a2b3c4d5e6f7g",
    "address": "user@example.com"
  }
}
```

List endpoints accept `page` and `perPage` (up to 100) and add a `pagination` object next to `data`:

```json
{
  "data": [],
  "pagination": {
    "page": 1,
    "perPage": 25,
    "total": 137,
    "totalPages": 6
  }
}
```

## Errors

`4xx` and `5xx` responses share one shape. Branch on `code` in your code. `error` is a readable message for logs and support tickets.

```json
{
  "error": "Mailbox not found.",
  "code": "ERR_MAILBOX_NOT_FOUND",
  "params": {}
}
```

## Rate limits

Too many requests in a short time return `429 Too Many Requests`. Wait before retrying. Repeatedly hitting the limit can get your IP address blocked for a while.

## Endpoints

* [Account](/emails/mail-api/account.md): the authenticated account and the mailboxes it can manage
* [Folders](/emails/mail-api/folders.md): list, create, rename and delete folders
* [Messages](/emails/mail-api/messages.md): list, search, read, flag, move and delete messages, and download attachments
* [Send](/emails/mail-api/send.md): send mail from a mailbox
* [Webhooks](/emails/mail-api/webhooks.md): get notified when something happens in a mailbox
* [Quota](/emails/mail-api/quota.md): storage and message usage
* [Feedback](/emails/mail-api/feedback.md): report a problem or missing capability in the API or the MCP server

## Other ways to use the Mail API

* **Code**: the [Email SDKs](/api-reference/email-sdks.md) for PHP, Python and TypeScript.
* **Terminal**: the `hostinger-mail` CLI, described on the same page.
* **AI assistants**: the email MCP server at `https://mcp.mail.hostinger.com/mcp`. See [Agentic Mail](/emails/agentic-mail.md#mcp-server).

***

*Last updated: October 27, 2026*