Galon Cloud
Galon Cloud

Galon Mail Pro

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

Markdown · API reference · OpenAPI

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

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

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)

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)

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

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)

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)

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

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)

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)

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.

MethodPathSummary
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.

StatusCodeWhennext_action
401api_key_missingNo Authorization: Bearer header.use_valid_api_key
403scope_missingThe key lacks mailpro:read or mailpro:write.add_missing_scope
422mailpro.request.invalidA malformed request (safe_details.field).fix_request
404mailpro.domain.not_foundNo domain with this id.check_resource_id
404mailpro.mailbox.not_foundNo mailbox with this id.check_resource_id
409mailpro.domain.not_verifiedCreating a mailbox before the domain is verified.resolve_conflict
409mailpro.domain.unavailableThis domain is already attached.resolve_conflict
409mailpro.mailbox.limit_reachedThe domain has its maximum of mailboxes.raise_limit_or_plan
409mailpro.identity.alias_limitThe mailbox has its maximum of aliases.raise_limit_or_plan
402mailpro.billing.payment_requiredThe balance does not cover the mailbox.top_up_balance
410mailpro.auth.activation_invalidThe activation link is used or expired.start_again
503mailpro.provider.unavailableTemporary: retry later.retry_later
next_actionWhat to do
use_valid_api_keySend 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_scopeThis 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_requestThe 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_idNothing 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_conflictThe 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_planA 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_balanceThe project balance does not cover this call. Top up the balance in USD in the console, then retry with the same Idempotency-Key.
start_againThis link, code or resource has expired. Start the operation again to get a new one.
retry_laterTemporary 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.

ItemPriceUnit
domain_monthly4.4 USDper domain a month
domain_annual44 USDper domain a year
mailbox_option1.65 USDper 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