# Galon Mail Pro

> Professional mailboxes on your own domain, managed by API: domains, mailboxes, aliases, quotas.

## Before you start

- A Galon account, a project and a key with `mailpro:write` and `mailpro:read`.
- A domain whose DNS you control. Mailboxes are billed from the prepaid balance.

## Quickstart

Every example reads `GALON_API_BASE` (`https://api.galon.ai/v1`) and `GALON_API_KEY` from the environment and prints the HTTP status and the JSON body.

**1. Set your key.** Export the base URL and your key.

**curl**

```bash
export GALON_API_BASE="https://api.galon.ai/v1"
export GALON_API_KEY="gln_..."
```

**2. Attach your domain.** The answer lists the DNS records to publish (an ownership TXT record, then MX, SPF, DKIM and DMARC).

**curl**

```bash
curl -sS -X POST "$GALON_API_BASE/mail-pro/domains" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "'"$GALON_MAILPRO_DOMAIN"'"}' \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/mail-pro/domains",
    data=json.dumps({"domain": os.environ["GALON_MAILPRO_DOMAIN"]}).encode(),
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
             "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/mail-pro/domains`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({domain: process.env.GALON_MAILPRO_DOMAIN}),
});
console.log(res.status, JSON.stringify(await res.json()));
```

**3. Verify it.** Once the records are published. Until then the answer is `200` with status `pending_verification`, not an error.

**curl**

```bash
curl -sS -X POST "$GALON_API_BASE/mail-pro/domains/${GALON_MAILPRO_DOMAIN_ID}/verify" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/mail-pro/domains/" + os.environ["GALON_MAILPRO_DOMAIN_ID"] + "/verify",
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
    method="POST",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/mail-pro/domains/${process.env.GALON_MAILPRO_DOMAIN_ID}/verify`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
```

**4. Create a mailbox.** With `activation: true`, the answer carries a single-use activation link (72 hours) so the person chooses their own password.

**curl**

```bash
curl -sS -X POST "$GALON_API_BASE/mail-pro/mailboxes" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain_id": "'"$GALON_MAILPRO_DOMAIN_ID"'", "local_part": "ana", "display_name": "Ana Example", "activation": true}' \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/mail-pro/mailboxes",
    data=json.dumps({"domain_id": os.environ["GALON_MAILPRO_DOMAIN_ID"], "local_part": "ana", "display_name": "Ana Example", "activation": True}).encode(),
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
             "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/mail-pro/mailboxes`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({domain_id: process.env.GALON_MAILPRO_DOMAIN_ID, local_part: "ana", display_name: "Ana Example", activation: true}),
});
console.log(res.status, JSON.stringify(await res.json()));
```

## Concepts

**Domains.** A domain is `pending_verification` until its ownership record is found, then `active`. `billing_cycle` is `monthly` or `annual`.

**Mailboxes.** Create, read, change the quota (`quota_mib`, at least 100), suspend, resume, delete. A deleted mailbox can be restored for 30 days.

**Aliases.** Up to 30 aliases per mailbox (`POST /v1/mail-pro/mailboxes/{id}/aliases`).

**Error format.** Mail Pro errors use `{"error": {"code", "message_key", "retryable", …}}`; `error.next_action` is added like on every Galon error.

## API reference

Derived from the OpenAPI 3.1 contract at each request: every operation of Galon Mail Pro you can reach today, with its full page (parameters, bodies, responses, examples). Base URL: the public API endpoint, `$GALON_API_BASE`.

| Method | Path | Summary |
|---|---|---|
| GET | [`/v1/mail-pro/domains`](/cloud/docs/api/mail-pro-domains) | List Mail Pro domains |
| POST | [`/v1/mail-pro/domains`](/cloud/docs/api/mail-pro-domains) | Attach a Mail Pro domain |
| GET | [`/v1/mail-pro/domains/{domain_id}`](/cloud/docs/api/mail-pro-domains-domain_id) | Get a Mail Pro domain |
| DELETE | [`/v1/mail-pro/domains/{domain_id}`](/cloud/docs/api/mail-pro-domains-domain_id) | Remove a Mail Pro domain |
| POST | [`/v1/mail-pro/domains/{domain_id}/verify`](/cloud/docs/api/mail-pro-domains-domain_id-verify) | Verify a Mail Pro domain |
| GET | [`/v1/mail-pro/mailboxes`](/cloud/docs/api/mail-pro-mailboxes) | List Mail Pro mailboxes |
| POST | [`/v1/mail-pro/mailboxes`](/cloud/docs/api/mail-pro-mailboxes) | Create a Mail Pro mailbox |
| GET | [`/v1/mail-pro/mailboxes/{mailbox_id}`](/cloud/docs/api/mail-pro-mailboxes-mailbox_id) | Get a Mail Pro mailbox |
| PATCH | [`/v1/mail-pro/mailboxes/{mailbox_id}`](/cloud/docs/api/mail-pro-mailboxes-mailbox_id) | Change a mailbox's quota |
| DELETE | [`/v1/mail-pro/mailboxes/{mailbox_id}`](/cloud/docs/api/mail-pro-mailboxes-mailbox_id) | Delete a mailbox (reversible for 30 days) |
| POST | [`/v1/mail-pro/mailboxes/{mailbox_id}/suspend`](/cloud/docs/api/mail-pro-mailboxes-mailbox_id-suspend) | Suspend a mailbox |
| POST | [`/v1/mail-pro/mailboxes/{mailbox_id}/resume`](/cloud/docs/api/mail-pro-mailboxes-mailbox_id-resume) | Reactivate a mailbox |
| POST | [`/v1/mail-pro/mailboxes/{mailbox_id}/aliases`](/cloud/docs/api/mail-pro-mailboxes-mailbox_id-aliases) | Add an alias to a mailbox |
| DELETE | [`/v1/mail-pro/mailboxes/{mailbox_id}/aliases/{address}`](/cloud/docs/api/mail-pro-mailboxes-mailbox_id-aliases-address) | Remove an alias |
| POST | [`/v1/mail-pro/mailboxes/{mailbox_id}/password`](/cloud/docs/api/mail-pro-mailboxes-mailbox_id-password) | Change a mailbox's password |
| POST | [`/v1/mail-pro/mailboxes/{mailbox_id}/activation-link`](/cloud/docs/api/mail-pro-mailboxes-mailbox_id-activation-link) | Send an activation link |
| POST | [`/v1/mail-pro/domains/{rid}/storage`](/cloud/docs/api/mail-pro-domains-rid-storage) | Buy storage for a domain |

## Errors

Every error is JSON: `{"detail": {"code", "message", "next_action"}}`. `next_action.code` is stable, `next_action.hint` says what to do next, and `console_url` is added when a person must act. The codes below are those this service returns.

| Status | Code | When | next_action |
|---|---|---|---|
| 401 | `api_key_missing` | No `Authorization: Bearer` header. | `use_valid_api_key` |
| 403 | `scope_missing` | The key lacks `mailpro:read` or `mailpro:write`. | `add_missing_scope` |
| 422 | `mailpro.request.invalid` | A malformed request (`safe_details.field`). | `fix_request` |
| 404 | `mailpro.domain.not_found` | No domain with this id. | `check_resource_id` |
| 404 | `mailpro.mailbox.not_found` | No mailbox with this id. | `check_resource_id` |
| 409 | `mailpro.domain.not_verified` | Creating a mailbox before the domain is verified. | `resolve_conflict` |
| 409 | `mailpro.domain.unavailable` | This domain is already attached. | `resolve_conflict` |
| 409 | `mailpro.mailbox.limit_reached` | The domain has its maximum of mailboxes. | `raise_limit_or_plan` |
| 409 | `mailpro.identity.alias_limit` | The mailbox has its maximum of aliases. | `raise_limit_or_plan` |
| 402 | `mailpro.billing.payment_required` | The balance does not cover the mailbox. | `top_up_balance` |
| 410 | `mailpro.auth.activation_invalid` | The activation link is used or expired. | `start_again` |
| 503 | `mailpro.provider.unavailable` | Temporary: retry later. | `retry_later` |

| next_action | What to do |
|---|---|
| `use_valid_api_key` | Send a valid Galon API key as 'Authorization: Bearer <key>'. If the key was revoked or has expired, create a new one in the console and retry with it. |
| `add_missing_scope` | This key does not have the scope this call needs. Create a key with that scope in the console, then retry the same call with the new key. |
| `fix_request` | The request is invalid. Fix it as 'message' and 'field' say, using the OpenAPI contract, then send it again. Do not retry it unchanged. |
| `check_resource_id` | Nothing with this id is visible to this key. List the resources to get a valid id, and check that the key belongs to the right project and environment (test or live). |
| `resolve_conflict` | The request conflicts with the resource state or with an earlier request under the same Idempotency-Key. Read the resource first; for a new intent, use a new Idempotency-Key. |
| `raise_limit_or_plan` | A plan quota or a spending limit is reached. Raise the limit or change the plan in the console, or wait for the next period, then retry. |
| `top_up_balance` | The project balance does not cover this call. Top up the balance in USD in the console, then retry with the same Idempotency-Key. |
| `start_again` | This link, code or resource has expired. Start the operation again to get a new one. |
| `retry_later` | Temporary error on Galon's side. Retry with exponential backoff and the same Idempotency-Key; if it lasts, contact support with the X-Request-Id header. |

## Limits, free tier and pricing

Usage prices, in US dollars, read from the price grid served by the platform each time this page is served. Paid from the prepaid balance.

| Item | Price | Unit |
|---|---|---|
| `domain_monthly` | 4.4 USD | per domain a month |
| `domain_annual` | 44 USD | per domain a year |
| `mailbox_option` | 1.65 USD | per mailbox a month |

Mail Pro is billed per domain from the prepaid balance, in US dollars; the amount charged for a mailbox is returned as `billed_minor`.

## FAQ

**Can people read their mail?**

This page covers the management API (domains, mailboxes, aliases).

**Is there an MCP tool for Mail Pro?**

Not yet: use the REST API.

**How is Mail Pro billed?**

Per domain, from the prepaid balance, monthly or annually (`billing_cycle`).

## More

- [Authentication](/cloud/docs/platform/authentication)
- [Projects: live and test](/cloud/docs/platform/environments)
- [Prepaid balance](/cloud/docs/platform/balance)
- [Quotas and rate limits](/cloud/docs/platform/quotas)
- [Terms of Service](/legal/terms-of-service)
- [Acceptable Use Policy](/legal/acceptable-use-policy)
- [Privacy Policy](/legal/privacy-policy)
- [Refunds and prepaid balance](/legal/prepaid-balance-and-refund-policy)
- [Legal Notice](/legal/legal-notice)
- [All legal documents](/legal)
