Galon Cloud
Galon Cloud

Galon Mail

Send transactional email from your server or your AI agent with one API key: verified sending domains, templates, suppressions, delivery status.

Markdown · API reference · OpenAPI

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 (and job:read to 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.

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

StatusCodeWhennext_action
401api_key_missingNo Authorization: Bearer header.use_valid_api_key
401api_key_invalidUnknown, revoked or expired key.use_valid_api_key
403scope_missingThe key lacks mail:send (or job:read for reads).add_missing_scope
403test_key_not_allowedA test key where this server sends for real.use_key_of_right_environment
403live_key_not_allowedA live key where this server only simulates.use_key_of_right_environment
403api_key_permission_insufficientA sending key on a domain or suppression route.use_full_access_key
403mail_key_domain_mismatchThe key is restricted to another domain.check_project_access
403mail_sender_not_allowedThe sender is not on a verified domain of the project.check_project_access
400idempotency_key_invalidMissing Idempotency-Key, or not 8 to 200 characters.fix_request
409idempotency_conflictSame key, different body.resolve_conflict
409mail_subscription_inactiveNo active Galon Mail plan (Free included).activate_mail_plan
409mail_no_verified_domainNo verified sending domain yet.add_and_verify_domain
409mail_account_not_readyThe account setup is not finished.resolve_conflict
403mail_account_suspendedSending is suspended for this account.check_project_access
422email_field_requiredA required field is missing (field names it).fix_request
422email_field_unknownA field the API does not accept.fix_request
422email_address_invalidAn address is not valid.fix_request
422email_too_many_recipientsMore than the recipient limit (to, cc and bcc together).fix_request
422email_content_requiredNeither text, html nor template.fix_request
422email_too_largeThe encoded message is over the size limit.fix_request
422email_scheduled_at_out_of_rangescheduled_at in the past or beyond the horizon.fix_request
422email_attachment_type_forbiddenAn attachment type that is never sent.fix_request
429mail_budget_exceededThe project's sending budget is reached.raise_limit_or_plan
404email_not_foundNo email with this id for this key.check_resource_id
409email_not_cancellableThe email already left.resolve_conflict
503mail_unavailableTemporary: retry with the same Idempotency-Key.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.
use_key_of_right_environmentThis 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_keyThis call needs a full_access key. Create one in the console, then retry with it.
check_project_accessThis project or key is not allowed to do this. Its owner must review the project, its key and its account in the console.
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.
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.
activate_mail_planActivate a Galon Mail plan (Free is available) in the console, then retry.
add_and_verify_domainAdd your sending domain and publish its DNS records, then verify it in the console.
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.
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).
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

Read from the platform code each time this page is served.

LimitValue
Recipients per email (to, cc and bcc together)50
Attachments per email10
Email size after encoding, attachments included25 MB
Emails per batch request100
Scheduling horizon (scheduled_at)3 days
Text or HTML body, each48 KiB
Message size after encoding, attachments included25 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.

PlanPrice per monthEmails per month
starter5.39 USD10,000
pro_50k15.00 USD50,000
pro_100k27.00 USD100,000
scale_250k62.00 USD250,000
scale_500k115.00 USD500,000
scale_1m210.00 USD1,000,000
scale_2_5m475.00 USD2,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.

More