Before you start
- A Galon account, a project and a key with
mailpro:writeandmailpro: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.
| 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).