List mail addresses belonging to a Project

GET/projects/{projectId}/mail-addresses/

API version

v2

Request method

GET

Operation ID

mail-list-mail-addresses

---

Request

• projectIdstring

  required

  ID of the Project to list MailAddresses for.

Responses

Response headers

• X-Pagination-Limitinteger

  The limit used to select the resources for the response

• X-Pagination-Skipinteger

  The number of skipped items

• X-Pagination-Pagenumber

  The calculate page of the list response. Refer to parameters to learn more.

• X-Pagination-TotalCountinteger

  The total amount of items available in the remote ressource. Use this value in combination with the limit to calculate the available pages.

Format

application/json

Description

OK

Schema documentation

• Array[
• *object
  • addressstring (idn-email)

    required
  • archiveobject

    required
    • activeboolean

      required

      shows if the mail-archive is enabled

    • quotainteger (int64)

      required

      maximum available mail-archive storage in bytes

    • usedBytesinteger (int64)

      required

      current mail-archive usage in bytes

  • autoResponderobject

    required
    • activeboolean

      required
    • expiresAtstring (date-time)
    • messagestring
    • startsAtstring (date-time)
  • forwardAddressesarray of string (idn-email)

    required
    • Array[
    • *string (idn-email)
    ]
• idstring (uuid)

  required
• isArchivedboolean

  required
• isBackupInProgressboolean

  required
• isCatchAllboolean

  required
• mailboxobject
  • namestring

    required
  • passwordUpdatedAtstring (date-time)

    required
  • sendingEnabledboolean

    required
  • spamProtectionobject

    required
    • activeboolean

      required
    • autoDeleteSpamboolean

      required
    • folderstring (one of: spam, inbox)

      required
    • relocationMinSpamScoreinteger

      required
  • storageInBytesobject

    required
    • currentobject

      required
      • updatedAtstring (date-time)

        required
      • valueinteger (int64)

        required
    • limitinteger (int64)

      required
• projectIdstring

  required
• receivingDisabledboolean

  required
• updatedAtstring (date-time)

  required

]

Example

Content-Type: application/json

[
  {
    "address": "email@mittwald.example",
    "archive": {
      "active": true,
      "quota": 123,
      "usedBytes": 123
    },
    "autoResponder": {
      "active": true,
      "expiresAt": "2025-11-03T18:08:45.234Z",
      "message": "string",
      "startsAt": "2025-11-03T18:08:45.234Z"
    },
    "forwardAddresses": [
      "email@mittwald.example"
    ],
    "id": "f0f86186-0a5a-45b2-aa33-502777496347",
    "isArchived": true,
    "isBackupInProgress": true,
    "isCatchAll": true,
    "mailbox": {
      "name": "string",
      "passwordUpdatedAt": "2025-11-03T18:08:45.234Z",
      "sendingEnabled": true,
      "spamProtection": {
        "active": true,
        "autoDeleteSpam": true,
        "folder": "spam",
        "relocationMinSpamScore": 123
      },
      "storageInBytes": {
        "current": {
          "updatedAt": "2025-11-03T18:08:45.234Z",
          "value": 123
        },
        "limit": 123
      }
    },
    "projectId": "string",
    "receivingDisabled": true,
    "updatedAt": "2025-11-03T18:08:45.234Z"
  }
]

JSON Schema

{
  "items": {
    "properties": {
      "address": {
        "format": "idn-email",
        "type": "string"
      },
      "archive": {
        "properties": {
          "active": {
            "description": "shows if the mail-archive is enabled",
            "type": "boolean"
          },
          "quota": {
            "description": "maximum available mail-archive storage in bytes",
            "format": "int64",
            "type": "integer"
          },
          "usedBytes": {
            "description": "current mail-archive usage in bytes",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "active",
          "quota",
          "usedBytes"
        ],
        "type": "object"
      },
      "autoResponder": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "expiresAt": {
            "format": "date-time",
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "startsAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "active"
        ],
        "type": "object"
      },
      "forwardAddresses": {
        "items": {
          "format": "idn-email",
          "type": "string"
        },
        "type": "array"
      },
      "id": {
        "format": "uuid",
        "type": "string"
      },
      "isArchived": {
        "type": "boolean"
      },
      "isBackupInProgress": {
        "type": "boolean"
      },
      "isCatchAll": {
        "type": "boolean"
      },
      "mailbox": {
        "properties": {
          "name": {
            "type": "string"
          },
          "passwordUpdatedAt": {
            "format": "date-time",
            "type": "string"
          },
          "sendingEnabled": {
            "type": "boolean"
          },
          "spamProtection": {
            "properties": {
              "active": {
                "type": "boolean"
              },
              "autoDeleteSpam": {
                "type": "boolean"
              },
              "folder": {
                "enum": [
                  "spam",
                  "inbox"
                ],
                "type": "string"
              },
              "relocationMinSpamScore": {
                "maximum": 10,
                "type": "integer"
              }
            },
            "required": [
              "active",
              "folder",
              "relocationMinSpamScore",
              "autoDeleteSpam"
            ],
            "type": "object"
          },
          "storageInBytes": {
            "properties": {
              "current": {
                "properties": {
                  "updatedAt": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "value": {
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "value",
                  "updatedAt"
                ],
                "type": "object"
              },
              "limit": {
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "limit",
              "current"
            ],
            "type": "object"
          }
        },
        "required": [
          "name",
          "sendingEnabled",
          "spamProtection",
          "storageInBytes",
          "passwordUpdatedAt"
        ],
        "type": "object"
      },
      "projectId": {
        "type": "string"
      },
      "receivingDisabled": {
        "type": "boolean"
      },
      "updatedAt": {
        "format": "date-time",
        "type": "string"
      }
    },
    "required": [
      "id",
      "receivingDisabled",
      "address",
      "isCatchAll",
      "projectId",
      "forwardAddresses",
      "updatedAt",
      "autoResponder",
      "isArchived",
      "isBackupInProgress",
      "archive"
    ],
    "type": "object"
  },
  "type": "array"
}

Usage examples

cURL

$ curl \
    --fail \
    --location \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    https://api.mittwald.de/v2/projects/string/mail-addresses?search=string&forwardAddress=true&catchAll=true&autoResponder=true&mailArchive=true&limit=50&page=1&sort=address.domain&order=asc

JavaScript SDK

import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
  
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.mail.listMailAddresses({
  "projectId": "string",
  "queryParameters": {
    "search": "string",
    "forwardAddress": true,
    "catchAll": true,
    "autoResponder": true,
    "mailArchive": true,
    "limit": 50,
    "page": 1,
    "sort": [
      "address.domain"
    ],
    "order": [
      "asc"
    ]
  }
});

assertStatus(response, 200);
  

PHP SDK

use \Mittwald\ApiClient\Generated\V2\Clients\Mail\ListMailAddresses\ListMailAddressesRequest;
  
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));

$request = (new ListMailAddressesRequest(
  projectId: "string"
))
  ->withSearch("string")
  ->withForwardAddress(true)
  ->withCatchAll(true)
  ->withAutoResponder(true)
  ->withMailArchive(true)
  ->withLimit(50)
  ->withPage(1)
  ->withSort(["address.domain"])
  ->withOrder(["asc"]);
$response = $client->mail()->listMailAddresses($request);

var_dump($response->getBody();