Before you start
- A Galon account and a project. In the console, accept the Galon Mail terms once and activate a plan (Free needs no card).
- A sending domain you control: console › Mail › Domains › add it, publish the DNS records shown, then verify. Nothing is sent from an unverified domain.
- A sending key with
mail:send(andjob:readto read the status back), created in the console (Mail › API keys) for the same environment as your project.
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. Keep the key server side: never in a browser, a mobile app or a repository.
curl
export GALON_API_BASE="https://api.galon.ai/v1"
export GALON_API_KEY="gln_..." # from the console, shown once
export GALON_MAIL_FROM="Acme <hello@your-verified-domain.com>"2. Check the key. GET /v1/tools lists what this key can do, its project and its environment. With MCP, get_status returns the same view.
curl
curl -sS -X GET "$GALON_API_BASE/tools" \
-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"] + "/tools",
headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
method="GET",
)
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}/tools`, {
method: "GET",
headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
MCP (JSON-RPC over HTTP)
curl -sS -X POST "$GALON_API_BASE/mcp" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_status", "arguments": {}}}' \
-w '\n%{http_code}\n'3. Send an email. An Idempotency-Key is required: one value per email, reused when you retry. The answer is 202 with the email job (email.id). Addresses delivered@, bounced@, complained@ and suppressed@test.galon.ai simulate each outcome and do not count towards your quota.
curl
curl -sS -X POST "$GALON_API_BASE/emails" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Idempotency-Key: quickstart-email-0001" \
-H "Content-Type: application/json" \
-d '{"from_email": "'"$GALON_MAIL_FROM"'", "to": ["delivered@test.galon.ai"], "subject": "Hello from Galon", "text": "It works."}' \
-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"] + "/emails",
data=json.dumps({"from_email": os.environ["GALON_MAIL_FROM"], "to": ["delivered@test.galon.ai"], "subject": "Hello from Galon", "text": "It works."}).encode(),
headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
"Idempotency-Key": "quickstart-email-0001",
"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}/emails`, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Idempotency-Key": "quickstart-email-0001", "Content-Type": "application/json" },
body: JSON.stringify({from_email: process.env.GALON_MAIL_FROM, to: ["delivered@test.galon.ai"], subject: "Hello from Galon", text: "It works."}),
});
console.log(res.status, JSON.stringify(await res.json()));
MCP (JSON-RPC over HTTP)
curl -sS -X POST "$GALON_API_BASE/mcp" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "send_email", "arguments": {"idempotency_key": "quickstart-email-0001", "from": "'"$GALON_MAIL_FROM"'", "to": ["delivered@test.galon.ai"], "subject": "Hello from Galon", "text": "It works."}}}' \
-w '\n%{http_code}\n'4. Read its status. The email is a job: status moves to a final state, with its delivery events.
curl
curl -sS -X GET "$GALON_API_BASE/emails/${GALON_EMAIL_ID}" \
-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"] + "/emails/" + os.environ["GALON_EMAIL_ID"],
headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
method="GET",
)
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}/emails/${process.env.GALON_EMAIL_ID}`, {
method: "GET",
headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
MCP (JSON-RPC over HTTP)
curl -sS -X POST "$GALON_API_BASE/mcp" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_email", "arguments": {"id": "'"$GALON_EMAIL_ID"'"}}}' \
-w '\n%{http_code}\n'Concepts
Sending domains. A domain is pending until its DNS records (SPF, DKIM, return path) are published and verified, then verified. Keys with full_access manage domains through /v1/domains (add, verify, read, delete); deleting needs the header Galon-Confirm: <exact domain>.
Keys: sending and full access. A sending key (sending_access) sends and reads; a full_access key also manages domains and suppressions. A key can be restricted to one domain: it then refuses any other sender (mail_key_domain_mismatch).
Emails are jobs. POST /v1/emails answers 202 with a job. Read it with GET /v1/emails/{id}; list with GET /v1/emails (filters: status, dates, tag, recipient). A scheduled email (scheduled_at, up to 72 hours ahead) can be rescheduled (PATCH) or cancelled (POST /v1/emails/{id}/cancel) until it leaves.
Idempotency. The same Idempotency-Key with the same body returns the same email (replayed: true); with a different body it answers 409 idempotency_conflict. Batches (POST /v1/emails/batch, up to 100 emails) take one key for the whole batch.
Templates and suppressions. Templates are versioned (/v1/templates, publish to make a version live; send with template: {id, variables}). Suppressed addresses are never sent to (/v1/suppressions).
API reference
Derived from the OpenAPI 3.1 contract at each request: every operation of Galon Mail 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/projects/{project_id}/mail/onboarding](/cloud/docs/api/projects-project_id-mail-onboarding) | Load or start Galon Mail onboarding |
| POST | [/v1/projects/{project_id}/mail/onboarding](/cloud/docs/api/projects-project_id-mail-onboarding) | Reply to the onboarding assistant |
| POST | [/v1/projects/{project_id}/mail/checkout](/cloud/docs/api/projects-project_id-mail-checkout) | Create or resume payment for a Galon Mail product |
| POST | [/v1/projects/{project_id}/mail/free](/cloud/docs/api/projects-project_id-mail-free) | Activate the Galon Mail free tier |
| GET | [/v1/projects/{project_id}/mail/subscription](/cloud/docs/api/projects-project_id-mail-subscription) | Get the Galon Mail subscription status |
| GET | [/v1/projects/{project_id}/mail/subscriptions](/cloud/docs/api/projects-project_id-mail-subscriptions) | Get Transactional and Marketing subscriptions |
| POST | [/v1/projects/{project_id}/mail/subscription/cancel](/cloud/docs/api/projects-project_id-mail-subscription-cancel) | Stop renewal of a Mail product (the plan remains active until the end of the paid period) |
| POST | [/v1/mail/consents](/cloud/docs/api/mail-consents) | Record a recipient's marketing consent |
| POST | [/v1/mail/consents/revoke](/cloud/docs/api/mail-consents-revoke) | Revoke a marketing consent |
| GET | [/v1/emails](/cloud/docs/api/emails) | List the project's email log |
| POST | [/v1/emails](/cloud/docs/api/emails) | Send a transactional email |
| GET | [/v1/emails/metrics](/cloud/docs/api/emails-metrics) | Get daily log metrics over at most 92 days |
| GET | [/v1/emails/bounce-reasons](/cloud/docs/api/emails-bounce-reasons) | Project bounce reasons over 7 or 30 days |
| GET | [/v1/deliverability](/cloud/docs/api/deliverability) | Deliverability by mailbox provider for the key's project (Gmail, Microsoft, Yahoo/AOL, Apple, Orange, others) over 7 and 30 days |
| GET | [/v1/projects/{project_id}/mail/deliverability](/cloud/docs/api/projects-project_id-mail-deliverability) | Deliverability by mailbox provider for the project (console) |
| POST | [/v1/emails/batch](/cloud/docs/api/emails-batch) | Send a batch of emails |
| POST | [/v1/emails/{job_id}/cancel](/cloud/docs/api/emails-job_id-cancel) | Cancel a send still queued (scheduled or not) |
| GET | [/v1/emails/{email_id}](/cloud/docs/api/emails-email_id) | Get an email and its retained timeline |
| PATCH | [/v1/emails/{email_id}](/cloud/docs/api/emails-email_id) | Reschedule an email before the worker picks it up |
| GET | [/v1/templates](/cloud/docs/api/templates) | List the project's templates |
| POST | [/v1/templates](/cloud/docs/api/templates) | Create a versioned template draft |
| GET | [/v1/templates/{template}](/cloud/docs/api/templates-template) | Get a template's draft and published state |
| PATCH | [/v1/templates/{template}](/cloud/docs/api/templates-template) | Update only a template's draft |
| DELETE | [/v1/templates/{template}](/cloud/docs/api/templates-template) | Delete a template and its versions |
| POST | [/v1/templates/{template}/publish](/cloud/docs/api/templates-template-publish) | Publish an immutable version of the draft |
| POST | [/v1/templates/{template}/duplicate](/cloud/docs/api/templates-template-duplicate) | Duplicate the draft into a new unpublished template without an alias |
| POST | [/v1/domains/claim](/cloud/docs/api/domains-claim) | Claim a domain already registered by another account (DNS proof): returns the TXT record to publish; no information about the holder |
| GET | [/v1/domains/claims/{claim_id}](/cloud/docs/api/domains-claims-claim_id) | Get a domain claim |
| POST | [/v1/domains/claims/{claim_id}/verify](/cloud/docs/api/domains-claims-claim_id-verify) | Check the TXT record and conclude: transferred (a NEW identity, to be verified, in the project) or blocked (domain active on another account) |
| POST | [/v1/email-validations](/cloud/docs/api/email-validations) | Validate email addresses (syntax, role, disposable domain, typo, MX) |
| GET | [/v1/domains](/cloud/docs/api/domains) | List Galon Mail sending domains |
| POST | [/v1/domains](/cloud/docs/api/domains) | Add a Galon Mail sending domain |
| GET | [/v1/domains/{domain_id}](/cloud/docs/api/domains-domain_id) | Get a sending domain and its DNS records |
| PATCH | [/v1/domains/{domain_id}](/cloud/docs/api/domains-domain_id) | Update the mutable options of a sending domain |
| DELETE | [/v1/domains/{domain_id}](/cloud/docs/api/domains-domain_id) | Delete a domain after exact confirmation |
| POST | [/v1/domains/{domain_id}/verify](/cloud/docs/api/domains-domain_id-verify) | Re-check a domain's DNS records |
| GET | [/v1/projects/{project_id}/mail/status](/cloud/docs/api/projects-project_id-mail-status) | Galon Mail for this account: armed, sending mode, identity, DNS records, payment available |
| POST | [/v1/projects/{project_id}/mail/dns/verify](/cloud/docs/api/projects-project_id-mail-dns-verify) | Check the sending domain's DNS records now (public DNS observed, re-read requested from the sending service); 1 call per minute per tenant |
| GET | [/v1/suppressions](/cloud/docs/api/suppressions) | List the suppression list |
| POST | [/v1/suppressions](/cloud/docs/api/suppressions) | Add addresses to the suppression list |
| DELETE | [/v1/suppressions/{target}](/cloud/docs/api/suppressions-target) | Remove an address from the suppression list |
| GET | [/v1/received-emails](/cloud/docs/api/received-emails) | List received emails |
| GET | [/v1/received-emails/{email_id}](/cloud/docs/api/received-emails-email_id) | Get a received email |
| GET | [/v1/received-emails/{email_id}/attachments](/cloud/docs/api/received-emails-email_id-attachments) | List a received email's attachments |
| GET | [/v1/received-emails/{email_id}/attachments/{attachment_id}](/cloud/docs/api/received-emails-email_id-attachments-attachment_id) | Download an attachment |
| POST | [/v1/received-emails/{email_id}/forward](/cloud/docs/api/received-emails-email_id-forward) | Forward a received email |
| GET | [/v1/receiving-domains](/cloud/docs/api/receiving-domains) | List inbound domains |
| POST | [/v1/receiving-domains](/cloud/docs/api/receiving-domains) | Register an inbound domain |
| GET | [/v1/receiving-domains/{domain_id}](/cloud/docs/api/receiving-domains-domain_id) | Get an inbound domain |
| PATCH | [/v1/receiving-domains/{domain_id}](/cloud/docs/api/receiving-domains-domain_id) | Enable or disable an inbound domain |
| DELETE | [/v1/receiving-domains/{domain_id}](/cloud/docs/api/receiving-domains-domain_id) | Remove an inbound domain |
| GET | [/v1/receiving-domains/{domain_id}/rules](/cloud/docs/api/receiving-domains-domain_id-rules) | List a domain's forwarding rules |
| POST | [/v1/receiving-domains/{domain_id}/rules](/cloud/docs/api/receiving-domains-domain_id-rules) | Create a forwarding rule |
| PATCH | [/v1/receiving-domains/{domain_id}/rules/{rule_id}](/cloud/docs/api/receiving-domains-domain_id-rules-rule_id) | Enable or disable a forwarding rule |
| DELETE | [/v1/receiving-domains/{domain_id}/rules/{rule_id}](/cloud/docs/api/receiving-domains-domain_id-rules-rule_id) | Delete a forwarding rule |
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 |
| 401 | api_key_invalid | Unknown, revoked or expired key. | use_valid_api_key |
| 403 | scope_missing | The key lacks mail:send (or job:read for reads). | add_missing_scope |
| 403 | test_key_not_allowed | A test key where this server sends for real. | use_key_of_right_environment |
| 403 | live_key_not_allowed | A live key where this server only simulates. | use_key_of_right_environment |
| 403 | api_key_permission_insufficient | A sending key on a domain or suppression route. | use_full_access_key |
| 403 | mail_key_domain_mismatch | The key is restricted to another domain. | check_project_access |
| 403 | mail_sender_not_allowed | The sender is not on a verified domain of the project. | check_project_access |
| 400 | idempotency_key_invalid | Missing Idempotency-Key, or not 8 to 200 characters. | fix_request |
| 409 | idempotency_conflict | Same key, different body. | resolve_conflict |
| 409 | mail_subscription_inactive | No active Galon Mail plan (Free included). | activate_mail_plan |
| 409 | mail_no_verified_domain | No verified sending domain yet. | add_and_verify_domain |
| 409 | mail_account_not_ready | The account setup is not finished. | resolve_conflict |
| 403 | mail_account_suspended | Sending is suspended for this account. | check_project_access |
| 422 | email_field_required | A required field is missing (field names it). | fix_request |
| 422 | email_field_unknown | A field the API does not accept. | fix_request |
| 422 | email_address_invalid | An address is not valid. | fix_request |
| 422 | email_too_many_recipients | More than the recipient limit (to, cc and bcc together). | fix_request |
| 422 | email_content_required | Neither text, html nor template. | fix_request |
| 422 | email_too_large | The encoded message is over the size limit. | fix_request |
| 422 | email_scheduled_at_out_of_range | scheduled_at in the past or beyond the horizon. | fix_request |
| 422 | email_attachment_type_forbidden | An attachment type that is never sent. | fix_request |
| 429 | mail_budget_exceeded | The project's sending budget is reached. | raise_limit_or_plan |
| 404 | email_not_found | No email with this id for this key. | check_resource_id |
| 409 | email_not_cancellable | The email already left. | resolve_conflict |
| 503 | mail_unavailable | Temporary: retry with the same Idempotency-Key. | 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. |
use_key_of_right_environment | This call is not allowed for this key's environment (test or live). Use a key of the other environment, created in the console. |
use_full_access_key | This call needs a full_access key. Create one in the console, then retry with it. |
check_project_access | This project or key is not allowed to do this. Its owner must review the project, its key and its account in the console. |
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. |
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. |
activate_mail_plan | Activate a Galon Mail plan (Free is available) in the console, then retry. |
add_and_verify_domain | Add your sending domain and publish its DNS records, then verify it in the console. |
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. |
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). |
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
Read from the platform code each time this page is served.
| Limit | Value |
|---|---|
| Recipients per email (to, cc and bcc together) | 50 |
| Attachments per email | 10 |
| Email size after encoding, attachments included | 25 MB |
| Emails per batch request | 100 |
| Scheduling horizon (scheduled_at) | 3 days |
| Text or HTML body, each | 48 KiB |
| Message size after encoding, attachments included | 25 MB |
Free plan (no card): 3,000 transactional emails a month, 100 a day. Hard limits: a send beyond them is refused, never billed.
Paid plans, per month, in US dollars. The plan's monthly volume is a hard limit: there is no overage billing.
| Plan | Price per month | Emails per month |
|---|---|---|
starter | 5.39 USD | 10,000 |
pro_50k | 15.00 USD | 50,000 |
pro_100k | 27.00 USD | 100,000 |
scale_250k | 62.00 USD | 250,000 |
scale_500k | 115.00 USD | 500,000 |
scale_1m | 210.00 USD | 1,000,000 |
scale_2_5m | 475.00 USD | 2,500,000 |
FAQ
Can my AI coding agent send email by itself?
Yes. Connect it to the Galon MCP server with the key; it calls get_status, then send_email with an idempotency_key. The account owner accepts the Galon Mail terms once in the console first.
Why does my first send answer 409?
mail_subscription_inactive: activate a plan (Free is available). mail_no_verified_domain: verify your sending domain. next_action.console_url opens the right console page.
How do I test without sending to real people?
Send to delivered@test.galon.ai (or bounced@, complained@, suppressed@, with an optional +label): the outcome is simulated and does not use your quota.
What happens when I reach my plan's volume?
On Free, sends are refused until the next period or a larger plan. On a paid plan, emails beyond the plan's volume are charged to the prepaid balance at the overage price shown on this page.