# Galon Mail

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

## 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**

```bash
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**

```bash
curl -sS -X GET "$GALON_API_BASE/tools" \
  -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"] + "/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)**

```js
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)**

```bash
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**

```bash
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)**

```python
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)**

```js
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)**

```bash
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**

```bash
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)**

```python
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)**

```js
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)**

```bash
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.

## 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)
