Firstmail API Docs

https://telegra.ph/Firstmail-api-docs-01-31
Admin
Firstmail API provides programmatic access to manage billing, dedicated servers, domains, and email...
Tokens:9,180
Snippets:33
Trust Score:5.9
Update:8 months ago
Show doc for...
Tokens:
Raw
### Get Dedicated Servers List - JSON Example

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves a list of the user's dedicated servers. The response is a JSON object with a success status and an array of server objects, each detailing ID, name, status, IP address, location, and specifications (CPU, RAM, disk, bandwidth).

```json
{
  "success": true,
  "data": [
    {
      "id": "ded-123",
      "name": "my-dedicated",
      "status": "running",
      "ip_address": "192.168.1.200",
      "location": "moscow",
      "specs": {
        "cpu": "Intel Xeon E5-2670",
        "ram": "32 GB DDR4",
        "disk": "1TB NVMe SSD",
        "bandwidth": "1Gbps"
      }
    }
  ]
}
```

--------------------------------

### Get User Balance - JSON Example

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves the current user balance and last updated information. This endpoint returns a JSON object with success status, balance amount, currency, and the timestamp of the last update.

```json
{
  "success": true,
  "data": {
    "balance": 1250.5,
    "currency": "RUB",
    "last_updated": "2026-01-31T20:56:23.806Z"
  }
}
```

--------------------------------

### Get Domain Details - JSON Example

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves comprehensive details for a specific domain, including DNS records and transaction history. The response is a JSON object with a success status and detailed domain information.

```json
{
  "success": true,
  "data": {
    "id": "domain-123",
    "name": "example.com",
    "status": "active",
    "expires": "2026-01-31T20:56:23.816Z",
    "auto_renew": true,
    "dns_managed": true
  }
}
```

--------------------------------

### Get Domains List - JSON Example

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves a list of the user's domains, including their status and expiration dates. The response is a JSON object with a success status and an array of domain objects, each containing ID, name, status, expiration date, auto-renewal status, and DNS management status.

```json
{
  "success": true,
  "data": [
    {
      "id": "domain-123",
      "name": "example.com",
      "status": "active",
      "expires": "2026-01-31T20:56:23.813Z",
      "auto_renew": true,
      "dns_managed": true
    }
  ]
}
```

--------------------------------

### Order Domain - JSON Example

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Creates an order for a new domain registration. The response confirms the order with a success status and provides the order ID.

```json
{
  "success": true,
  "data": {
    "order_id": "string"
  }
}
```

--------------------------------

### Order Dedicated Server - JSON Example

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Creates an order for a new dedicated server. The response confirms the order with a success status and returns data for the newly ordered server, including its ID, name, status, IP address, location, and specifications.

```json
{
  "success": true,
  "data": {
    "id": "ded-123",
    "name": "my-dedicated",
    "status": "running",
    "ip_address": "192.168.1.200",
    "location": "moscow",
    "specs": {
      "cpu": "Intel Xeon E5-2670",
      "ram": "32 GB DDR4",
      "disk": "1TB NVMe SSD",
      "bandwidth": "1Gbps"
    }
  }
}
```

--------------------------------

### Get Domain Status - JSON Example

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves the current status and registration information for a specific domain. The response is a JSON object with a success status and data including the domain's status, expiration date, and registrar lock status.

```json
{
  "success": true,
  "data": {
    "status": "active",
    "expires_at": "2026-01-31T20:56:23.815Z",
    "registrar_lock": false
  }
}
```

--------------------------------

### GET /balance

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves the user's current balance and information about the last update.

```APIDOC
## GET /balance

### Description
Retrieves the user's current balance and information about the last update.

### Method
GET

### Endpoint
/balance

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains balance information.
  - **balance** (number) - The current balance amount.
  - **currency** (string) - The currency of the balance.
  - **last_updated** (string) - The timestamp of the last balance update.

#### Response Example
```json
{
  "success": true,
  "data": {
    "balance": 1250.5,
    "currency": "RUB",
    "last_updated": "2026-01-31T20:56:23.806Z"
  }
}
```
```

--------------------------------

### GET /servers/dedicated

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves a list of the user's dedicated servers.

```APIDOC
## GET /servers/dedicated

### Description
Retrieves a list of the user's dedicated servers.

### Method
GET

### Endpoint
/servers/dedicated

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - A list of dedicated server objects.
  - **id** (string) - The unique identifier for the dedicated server.
  - **name** (string) - The name of the dedicated server.
  - **status** (string) - The current status of the server (e.g., 'running').
  - **ip_address** (string) - The IP address of the server.
  - **location** (string) - The physical location of the server.
  - **specs** (object) - The specifications of the server.
    - **cpu** (string) - CPU details.
    - **ram** (string) - RAM details.
    - **disk** (string) - Disk details.
    - **bandwidth** (string) - Bandwidth details.

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "ded-123",
      "name": "my-dedicated",
      "status": "running",
      "ip_address": "192.168.1.200",
      "location": "moscow",
      "specs": {
        "cpu": "Intel Xeon E5-2670",
        "ram": "32 GB DDR4",
        "disk": "1TB NVMe SSD",
        "bandwidth": "1Gbps"
      }
    }
  ]
}
```
```

--------------------------------

### GET /domains

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves a list of the user's domains with status and expiration information.

```APIDOC
## GET /domains

### Description
Retrieves a list of the user's domains with status and expiration information.

### Method
GET

### Endpoint
/domains

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - A list of domain objects.
  - **id** (string) - The unique identifier for the domain.
  - **name** (string) - The domain name.
  - **status** (string) - The current status of the domain (e.g., 'active').
  - **expires** (string) - The expiration date of the domain.
  - **auto_renew** (boolean) - Indicates if auto-renewal is enabled.
  - **dns_managed** (boolean) - Indicates if DNS is managed.

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "domain-123",
      "name": "example.com",
      "status": "active",
      "expires": "2026-01-31T20:56:23.813Z",
      "auto_renew": true,
      "dns_managed": true
    }
  ]
}
```
```

--------------------------------

### Get Transaction History - JSON Example

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves a list of financial transactions with filtering and pagination capabilities. The response is a JSON object containing a success status and an array of transaction objects, each with details like ID, amount, currency, type, description, status, and creation date.

```json
{
  "success": true,
  "data": [
    {
      "id": "tx-123",
      "amount": 1000,
      "currency": "RUB",
      "transaction_type": "payment",
      "description": "Пополнение баланса",
      "status": "completed",
      "created_at": "2026-01-31T20:56:23.807Z"
    }
  ]
}
```

--------------------------------

### GET /transactions

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves a list of financial transactions with filtering and pagination capabilities.

```APIDOC
## GET /transactions

### Description
Retrieves a list of financial transactions with the ability to filter and paginate.

### Method
GET

### Endpoint
/transactions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - A list of transaction objects.
  - **id** (string) - The unique identifier for the transaction.
  - **amount** (number) - The transaction amount.
  - **currency** (string) - The currency of the transaction.
  - **transaction_type** (string) - The type of transaction (e.g., 'payment').
  - **description** (string) - A description of the transaction.
  - **status** (string) - The status of the transaction (e.g., 'completed').
  - **created_at** (string) - The timestamp when the transaction was created.

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "tx-123",
      "amount": 1000,
      "currency": "RUB",
      "transaction_type": "payment",
      "description": "Пополнение баланса",
      "status": "completed",
      "created_at": "2026-01-31T20:56:23.807Z"
    }
  ]
}
```
```

--------------------------------

### GET /domains/{domain_id}/status

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves the current status and registration information for a specific domain.

```APIDOC
## GET /domains/{domain_id}/status

### Description
Retrieves the current status of a domain and its registration information.

### Method
GET

### Endpoint
/domains/{domain_id}/status

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID of the domain.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains domain status information.
  - **status** (string) - The current status of the domain (e.g., 'active').
  - **expires_at** (string) - The expiration date of the domain.
  - **registrar_lock** (boolean) - Indicates if the registrar lock is enabled.

#### Response Example
```json
{
  "success": true,
  "data": {
    "status": "active",
    "expires_at": "2026-01-31T20:56:23.815Z",
    "registrar_lock": false
  }
}
```
```

--------------------------------

### GET /domains/{domainId}

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves detailed information about a specific domain, including DNS records and transaction history.

```APIDOC
## GET /domains/{domainId}

### Description
Retrieves full information about a domain, including DNS records and transaction history.

### Method
GET

### Endpoint
/domains/{domainId}

### Parameters
#### Path Parameters
- **domainId** (string) - Required - The ID of the domain.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains detailed domain information.
  - **id** (string) - The unique identifier for the domain.
  - **name** (string) - The domain name.
  - **status** (string) - The current status of the domain (e.g., 'active').
  - **expires** (string) - The expiration date of the domain.
  - **auto_renew** (boolean) - Indicates if auto-renewal is enabled.
  - **dns_managed** (boolean) - Indicates if DNS is managed.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "domain-123",
    "name": "example.com",
    "status": "active",
    "expires": "2026-01-31T20:56:23.816Z",
    "auto_renew": true,
    "dns_managed": true
  }
}
```
```

--------------------------------

### Get Email Messages by Credentials

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves a list of emails from a mailbox using login and password. Supports filtering and pagination. Requires valid email credentials.

```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "msg-123",
        "uid": 1234,
        "subject": "Test message",
        "from": "sender@example.com",
        "to": [
          "string"
        ],
        "cc": [
          "string"
        ],
        "bcc": [
          "string"
        ],
        "date": "2026-01-31T20:56:23.821Z",
        "size": 2048,
        "flags": [
          "string"
        ],
        "is_read": false,
        "is_flagged": false,
        "body_text": "string",
        "body_html": "string",
        "headers": {},
        "attachments": [
          {
            "filename": "string",
            "size": 0,
            "content_type": "string",
            "content_id": "string"
          }
        ]
      }
    ],
    "total_count": 25,
    "unread_count": 5
  }
}
```

--------------------------------

### Get Unread Email Messages

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves only new, unread emails from the mailbox. This endpoint helps in focusing on new communications. Requires valid email credentials.

```json
{
  "success": true,
  "data": {
    "unread_messages": [
      {
        "id": "msg-123",
        "uid": 1234,
        "subject": "Test message",
        "from": "sender@example.com",
        "to": [
          "string"
        ],
        "cc": [
          "string"
        ],
        "bcc": [
          "string"
        ],
        "date": "2026-01-31T20:56:23.827Z",
        "size": 2048,
        "flags": [
          "string"
        ],
        "is_read": false,
        "is_flagged": false,
        "body_text": "string",
        "body_html": "string",
        "headers": {},
        "attachments": [
          {
            "filename": "string",
            "size": 0,
            "content_type": "string",
            "content_id": "string"
          }
        ]
      }
    ],
    "unread_count": 3,
    "total_messages": 47
  }
}
```

--------------------------------

### Get Latest Email Message

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves the most recently received email from a mailbox. This endpoint is useful for quickly accessing the latest communication. Requires valid email credentials.

```json
{
  "success": true,
  "data": {
    "id": "msg-123",
    "uid": 1234,
    "subject": "Test message",
    "from": "sender@example.com",
    "to": [
      "string"
    ],
    "cc": [
      "string"
    ],
    "bcc": [
      "string"
    ],
    "date": "2026-01-31T20:56:23.824Z",
    "size": 2048,
    "flags": [
      "string"
    ],
    "is_read": false,
    "is_flagged": false,
    "body_text": "string",
    "body_html": "string",
    "headers": {},
    "attachments": [
      {
        "filename": "string",
        "size": 0,
        "content_type": "string",
        "content_id": "string"
      }
    ]
  }
}
```

--------------------------------

### Order VPS Server

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Creates an order for a new VPS server.

```APIDOC
## POST /servers/vps/order

### Description
Creates an order for a new VPS server.

### Method
POST

### Endpoint
/servers/vps/order

### Parameters
#### Request Body
- **plan** (string) - Required - The desired VPS plan.
- **location** (string) - Required - The desired location for the VPS.
- **name** (string) - Optional - A name for the VPS.

### Request Example
```json
{
  "plan": "vps-basic",
  "location": "moscow",
  "name": "my-new-vps"
}
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains details of the created VPS order.
  - **id** (string) - The unique identifier for the VPS.
  - **name** (string) - The name of the VPS.
  - **status** (string) - The initial status of the VPS.
  - **ip_address** (string) - The IP address assigned to the VPS.
  - **plan** (string) - The VPS plan.
  - **location** (string) - The location of the VPS.
  - **specs** (object) - Specifications of the VPS.
    - **cpu** (string) - CPU details.
    - **ram** (string) - RAM details.
    - **disk** (string) - Disk details.

#### Response Example (201 Created)
```json
{
  "success": true,
  "data": {
    "id": "vps-456",
    "name": "my-new-vps",
    "status": "pending",
    "ip_address": "192.168.2.200",
    "plan": "vps-basic",
    "location": "moscow",
    "specs": {
      "cpu": "2 vCPU",
      "ram": "4 GB",
      "disk": "80 GB SSD"
    }
  }
}
```
```

--------------------------------

### POST /domains/order

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Creates an order for a new domain registration.

```APIDOC
## POST /domains/order

### Description
Creates an order for a new domain registration.

### Method
POST

### Endpoint
/domains/order

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
*Note: The request body schema is not provided in the input.* 

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains information about the order.
  - **order_id** (string) - The unique identifier for the domain order.

#### Response Example
```json
{
  "success": true,
  "data": {
    "order_id": "string"
  }
}
```
```

--------------------------------

### Order VPS Server Success Response (JSON)

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

This JSON output confirms the successful creation of a VPS server order. It returns a success status and a data object mirroring the details of the newly ordered VPS, including its ID, name, status, and specifications.

```json
{
  "success": true,
  "data": {
    "id": "vps-123",
    "name": "my-vps",
    "status": "running",
    "ip_address": "192.168.1.100",
    "plan": "vps-basic",
    "location": "moscow",
    "specs": {
      "cpu": "2 vCPU",
      "ram": "4 GB",
      "disk": "80 GB SSD"
    }
  }
}
```

--------------------------------

### List VPS Servers

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves a list of the user's VPS servers and their current status.

```APIDOC
## GET /servers/vps

### Description
Returns a list of the user's VPS servers and their current status.

### Method
GET

### Endpoint
/servers/vps

### Parameters
#### Query Parameters
No query parameters are available for this endpoint.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (array) - A list of VPS server objects.
  - **id** (string) - The unique identifier for the VPS.
  - **name** (string) - The name of the VPS.
  - **status** (string) - The current status of the VPS (e.g., 'running').
  - **ip_address** (string) - The IP address of the VPS.
  - **plan** (string) - The VPS plan.
  - **location** (string) - The location of the VPS.
  - **specs** (object) - Specifications of the VPS.
    - **cpu** (string) - CPU details.
    - **ram** (string) - RAM details.
    - **disk** (string) - Disk details.

#### Response Example (200 OK)
```json
{
  "success": true,
  "data": [
    {
      "id": "vps-123",
      "name": "my-vps",
      "status": "running",
      "ip_address": "192.168.1.100",
      "plan": "vps-basic",
      "location": "moscow",
      "specs": {
        "cpu": "2 vCPU",
        "ram": "4 GB",
        "disk": "80 GB SSD"
      }
    }
  ]
}
```
```

--------------------------------

### POST /servers/dedicated/order

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Creates an order for a new dedicated server.

```APIDOC
## POST /servers/dedicated/order

### Description
Creates an order for a new dedicated server.

### Method
POST

### Endpoint
/servers/dedicated/order

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
*Note: The request body schema is not provided in the input.* 

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains information about the ordered server.
  - **id** (string) - The unique identifier for the dedicated server.
  - **name** (string) - The name of the dedicated server.
  - **status** (string) - The current status of the server (e.g., 'running').
  - **ip_address** (string) - The IP address of the server.
  - **location** (string) - The physical location of the server.
  - **specs** (object) - The specifications of the server.
    - **cpu** (string) - CPU details.
    - **ram** (string) - RAM details.
    - **disk** (string) - Disk details.
    - **bandwidth** (string) - Bandwidth details.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "ded-123",
    "name": "my-dedicated",
    "status": "running",
    "ip_address": "192.168.1.200",
    "location": "moscow",
    "specs": {
      "cpu": "Intel Xeon E5-2670",
      "ram": "32 GB DDR4",
      "disk": "1TB NVMe SSD",
      "bandwidth": "1Gbps"
    }
  }
}
```
```

--------------------------------

### List VPS Servers Response (JSON)

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

This JSON structure represents the successful retrieval of a list of VPS servers. It includes a success status and an array of server objects, each detailing its ID, name, status, IP address, plan, location, and specifications.

```json
{
  "success": true,
  "data": [
    {
      "id": "vps-123",
      "name": "my-vps",
      "status": "running",
      "ip_address": "192.168.1.100",
      "plan": "vps-basic",
      "location": "moscow",
      "specs": {
        "cpu": "2 vCPU",
        "ram": "4 GB",
        "disk": "80 GB SSD"
      }
    }
  ]
}
```

--------------------------------

### POST /email/messages

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves a list of emails from a mailbox using login and password.

```APIDOC
## POST /email/messages

### Description
Retrieves a list of emails from a mailbox using login and password.

### Method
POST

### Endpoint
/email/messages

### Parameters
#### Path Parameters
No path parameters.

#### Query Parameters
No query parameters.

#### Request Body
- **login** (string) - Required - The user's login.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "login": "user@example.com",
  "password": "your_password"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the email messages and counts.
  - **messages** (array) - A list of email messages.
    - **id** (string) - Unique identifier for the message.
    - **uid** (integer) - Unique ID of the message on the server.
    - **subject** (string) - The subject of the email.
    - **from** (string) - The sender's email address.
    - **to** (array) - List of recipients.
    - **cc** (array) - List of CC recipients.
    - **bcc** (array) - List of BCC recipients.
    - **date** (string) - The date and time the email was sent (ISO 8601 format).
    - **size** (integer) - The size of the email in bytes.
    - **flags** (array) - Flags associated with the email (e.g., \"seen\").
    - **is_read** (boolean) - Whether the email has been read.
    - **is_flagged** (boolean) - Whether the email is flagged.
    - **body_text** (string) - The plain text body of the email.
    - **body_html** (string) - The HTML body of the email.
    - **headers** (object) - Key-value pairs of email headers.
    - **attachments** (array) - List of attachments.
      - **filename** (string) - The name of the attachment.
      - **size** (integer) - The size of the attachment in bytes.
      - **content_type** (string) - The MIME type of the attachment.
      - **content_id** (string) - The content ID of the attachment.
  - **total_count** (integer) - The total number of messages in the mailbox.
  - **unread_count** (integer) - The number of unread messages.

#### Error Response (401)
- **success** (boolean) - Indicates if the request was successful (will be false).
- **error** (string) - A message describing the error.
- **details** (object) - Additional error details.

#### Response Example (200)
```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "msg-123",
        "uid": 1234,
        "subject": "Test message",
        "from": "sender@example.com",
        "to": ["string"],
        "cc": ["string"],
        "bcc": ["string"],
        "date": "2026-01-31T20:56:23.821Z",
        "size": 2048,
        "flags": ["string"],
        "is_read": false,
        "is_flagged": false,
        "body_text": "string",
        "body_html": "string",
        "headers": {},
        "attachments": [
          {
            "filename": "string",
            "size": 0,
            "content_type": "string",
            "content_id": "string"
          }
        ]
      }
    ],
    "total_count": 25,
    "unread_count": 5
  }
}
```

#### Response Example (401)
```json
{
  "success": false,
  "error": "Invalid login or password",
  "details": {}
}
```
```

--------------------------------

### POST /email/messages/latest

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves the latest received email from the mailbox.

```APIDOC
## POST /email/messages/latest

### Description
Retrieves the latest received email from the mailbox.

### Method
POST

### Endpoint
/email/messages/latest

### Parameters
#### Path Parameters
No path parameters.

#### Query Parameters
No query parameters.

#### Request Body
- **login** (string) - Required - The user's login.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "login": "user@example.com",
  "password": "your_password"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the latest email message.
  - **id** (string) - Unique identifier for the message.
  - **uid** (integer) - Unique ID of the message on the server.
  - **subject** (string) - The subject of the email.
  - **from** (string) - The sender's email address.
  - **to** (array) - List of recipients.
  - **cc** (array) - List of CC recipients.
  - **bcc** (array) - List of BCC recipients.
  - **date** (string) - The date and time the email was sent (ISO 8601 format).
  - **size** (integer) - The size of the email in bytes.
  - **flags** (array) - Flags associated with the email (e.g., \"seen\").
  - **is_read** (boolean) - Whether the email has been read.
  - **is_flagged** (boolean) - Whether the email is flagged.
  - **body_text** (string) - The plain text body of the email.
  - **body_html** (string) - The HTML body of the email.
  - **headers** (object) - Key-value pairs of email headers.
  - **attachments** (array) - List of attachments.
    - **filename** (string) - The name of the attachment.
    - **size** (integer) - The size of the attachment in bytes.
    - **content_type** (string) - The MIME type of the attachment.
    - **content_id** (string) - The content ID of the attachment.

#### Error Response (404)
- **success** (boolean) - Indicates if the request was successful (will be false).
- **error** (string) - A message describing the error.
- **details** (object) - Additional error details.

#### Response Example (200)
```json
{
  "success": true,
  "data": {
    "id": "msg-123",
    "uid": 1234,
    "subject": "Test message",
    "from": "sender@example.com",
    "to": ["string"],
    "cc": ["string"],
    "bcc": ["string"],
    "date": "2026-01-31T20:56:23.824Z",
    "size": 2048,
    "flags": ["string"],
    "is_read": false,
    "is_flagged": false,
    "body_text": "string",
    "body_html": "string",
    "headers": {},
    "attachments": [
      {
        "filename": "string",
        "size": 0,
        "content_type": "string",
        "content_id": "string"
      }
    ]
  }
}
```

#### Response Example (404)
```json
{
  "success": false,
  "error": "Messages not found",
  "details": {}
}
```
```

--------------------------------

### POST /email/password/change/

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Changes the password for the email account. Only available if two-factor authentication (2FA) or a recovery email is not set.

```APIDOC
## POST /email/password/change/

### Description
Changes the password for the email account. This endpoint is only available if two-factor authentication (2FA) or a recovery email is not set for the account.

### Method
POST

### Endpoint
/email/password/change/

### Parameters
#### Path Parameters
No path parameters.

#### Query Parameters
No query parameters.

#### Request Body
- **login** (string) - Required - The user's login.
- **old_password** (string) - Required - The current password.
- **new_password** (string) - Required - The new password.

### Request Example
```json
{
  "login": "user@example.com",
  "old_password": "current_password",
  "new_password": "new_secure_password"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the password change was successful.

#### Error Response (e.g., 400, 401, 403)
- **success** (boolean) - Indicates if the request was successful (will be false).
- **error** (string) - A message describing the error (e.g., \"Invalid credentials\", \"2FA is enabled\").
- **details** (object) - Additional error details.

#### Response Example (200)
```json
{
  "success": true
}
```

#### Response Example (Error)
```json
{
  "success": false,
  "error": "Password change failed. 2FA is enabled.",
  "details": {}
}
```
```

--------------------------------

### Mailbox Not Found Response (JSON)

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

This JSON object is returned when a requested email mailbox cannot be found. It indicates a failed operation with a success status of false and an error message specifying that the mailbox does not exist.

```json
{
  "success": false,
  "error": "Почтовый ящик не найден"
}
```

--------------------------------

### Change Password

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Allows users to change their email account password. Supports different response codes for success and various error conditions.

```APIDOC
## POST /change-password

### Description
Changes the password for an email account.

### Method
POST

### Endpoint
/change-password

### Parameters
#### Request Body
- **current_password** (string) - Required - The current password of the user.
- **new_password** (string) - Required - The new password for the user.

### Request Example
```json
{
  "current_password": "oldPassword123",
  "new_password": "newSecurePassword456"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - A confirmation message.
- **data** (object) - Contains details about the password change.
  - **email** (string) - The email address.
  - **password_changed_at** (string) - The timestamp when the password was changed.

#### Response Example (200 OK)
```json
{
  "success": true,
  "message": "Пароль успешно изменен",
  "data": {
    "email": "user@firstmail.ru",
    "password_changed_at": "2026-01-31T20:56:23.830Z"
  }
}
```

#### Error Responses
- **400 Bad Request**: Validation error or password cannot be changed (e.g., 2FA enabled, weak password).
  - **error** (string) - Description of the error.
  - Example: `{"success": false, "error": "Невозможно изменить пароль: установлена двухфакторная аутентификация"}`
- **401 Unauthorized**: Incorrect current password.
  - **error** (string) - Description of the error.
  - Example: `{"success": false, "error": "Неверный текущий пароль"}`
- **404 Not Found**: Mailbox not found.
  - **error** (string) - Description of the error.
  - Example: `{"success": false, "error": "Почтовый ящик не найден"}`
```

--------------------------------

### POST /email/messages/unread

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Retrieves only new unread emails from the mailbox.

```APIDOC
## POST /email/messages/unread

### Description
Retrieves only new unread emails from the mailbox.

### Method
POST

### Endpoint
/email/messages/unread

### Parameters
#### Path Parameters
No path parameters.

#### Query Parameters
No query parameters.

#### Request Body
- **login** (string) - Required - The user's login.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "login": "user@example.com",
  "password": "your_password"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the unread email messages and counts.
  - **unread_messages** (array) - A list of unread email messages.
    - **id** (string) - Unique identifier for the message.
    - **uid** (integer) - Unique ID of the message on the server.
    - **subject** (string) - The subject of the email.
    - **from** (string) - The sender's email address.
    - **to** (array) - List of recipients.
    - **cc** (array) - List of CC recipients.
    - **bcc** (array) - List of BCC recipients.
    - **date** (string) - The date and time the email was sent (ISO 8601 format).
    - **size** (integer) - The size of the email in bytes.
    - **flags** (array) - Flags associated with the email (e.g., \"seen\").
    - **is_read** (boolean) - Whether the email has been read.
    - **is_flagged** (boolean) - Whether the email is flagged.
    - **body_text** (string) - The plain text body of the email.
    - **body_html** (string) - The HTML body of the email.
    - **headers** (object) - Key-value pairs of email headers.
    - **attachments** (array) - List of attachments.
      - **filename** (string) - The name of the attachment.
      - **size** (integer) - The size of the attachment in bytes.
      - **content_type** (string) - The MIME type of the attachment.
      - **content_id** (string) - The content ID of the attachment.
  - **unread_count** (integer) - The number of unread messages.
  - **total_messages** (integer) - The total number of messages in the mailbox.

#### Response Example (200)
```json
{
  "success": true,
  "data": {
    "unread_messages": [
      {
        "id": "msg-123",
        "uid": 1234,
        "subject": "Test message",
        "from": "sender@example.com",
        "to": ["string"],
        "cc": ["string"],
        "bcc": ["string"],
        "date": "2026-01-31T20:56:23.827Z",
        "size": 2048,
        "flags": ["string"],
        "is_read": false,
        "is_flagged": false,
        "body_text": "string",
        "body_html": "string",
        "headers": {},
        "attachments": [
          {
            "filename": "string",
            "size": 0,
            "content_type": "string",
            "content_id": "string"
          }
        ]
      }
    ],
    "unread_count": 3,
    "total_messages": 47
  }
}
```
```

--------------------------------

### Password Change Success Response (JSON)

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

This JSON object represents a successful password change operation. It includes a success status, a confirmation message, and details about the email and when the password was last changed.

```json
{
  "success": true,
  "message": "Пароль успешно изменен",
  "data": {
    "email": "user@firstmail.ru",
    "password_changed_at": "2026-01-31T20:56:23.830Z"
  }
}
```

--------------------------------

### Password Change Error Response (JSON)

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

This JSON object indicates an error during a password change attempt. It specifies the reason for the failure, such as validation errors or security configurations like two-factor authentication being enabled.

```json
{
  "success": false,
  "error": "Невозможно изменить пароль: установлена двухфакторная аутентификация"
}
```

--------------------------------

### Invalid Current Password Response (JSON)

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

This JSON response signifies an authentication failure due to an incorrect current password. It returns a success status of false and an error message indicating the issue.

```json
{
  "success": false,
  "error": "Неверный текущий пароль"
}
```

--------------------------------

### Change Mailbox Password

Source: https://telegra.ph/Firstmail-api-docs-01-31/index

Changes the password for a mailbox. This operation is restricted and only available if two-factor authentication (2FA) is not set up or a recovery email is not configured.

```json
{
  "success": false,
  "error": "Error message",
  "details": {}
}
```
Tokens:
Raw