Galon Cloud
Galon Cloud · Guide

Send your first email with the API

From an empty project to a delivered email in five minutes: activate Galon Mail, create a sending key, call POST /v1/emails, read the status.

Markdown · API reference · llms.txt

Before you start

1. Activate Galon Mail

Console › Mail. Accept the Galon Mail terms once (Read and accept the terms), then Activate Galon Mail to start on the Free plan.

The Galon Mail overview in the console: a dark card titled Galon Mail, Free plan, one click, with an Activate Galon Mail button, and below it a notice asking to read and accept the Galon Mail terms before any sending.
Terms first, then the plan.

2. Set your key

Create a key with Send emails (Create an API key) and export it with the API base. Keep it server side.

export GALON_API_BASE="https://api.galon.ai/v1"
export GALON_API_KEY="gln_..."      # from the console, shown once: never commit it
export GALON_MAIL_FROM="Acme <hello@your-verified-domain.com>"

3. Check what the key can do

GET /v1/tools lists the tools this key may call, its project and its environment. mail.send must be in the list.

curl -s "$GALON_API_BASE/tools" \
  -H "Authorization: Bearer $GALON_API_KEY"

Expected output

{
  "tools": [ { "id": "mail.send", "scope": "mail:send", ... } ],
  "project_id": "…",
  "environment": "live"
}

With MCP: get_status

{"tool": "get_status", "arguments": {}}

4. Send the email

One Idempotency-Key per email, reused if you retry. The answer is 202 with the email job. The address delivered@test.galon.ai simulates a delivery and does not count towards your quota.

curl -s -X POST "$GALON_API_BASE/emails" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-email-0001" \
  -d "{\"from_email\": \"$GALON_MAIL_FROM\", \"to\": [\"delivered@test.galon.ai\"], \"subject\": \"Hello from Galon\", \"text\": \"It works.\"}"

Expected output

{
  "schema": "galon.api.submission.v1",
  "object": "job_submission",
  "job": { "id": "…", "type": "mail.send", "status": "queued", ... },
  "replayed": false,
  "idempotency": { "status": "created", "same_key_required_for_retry": true, "key_returned": false },
  "email": { "id": "…", ... }
}
A terminal: the curl command that posts to /emails with an Idempotency-Key, and its JSON answer: schema galon.api.submission.v1, a job of type mail.send with status queued, replayed false, and the idempotency block. Identifiers are replaced by an ellipsis.
The answer comes back at once: the email is a job, sent in the background.

With MCP: send_email

{"tool": "send_email", "arguments": {"idempotency_key": "first-email-0001", "from": "$GALON_MAIL_FROM", "to": ["delivered@test.galon.ai"], "subject": "Hello from Galon", "text": "It works."}}

5. Read its status

Use the email.id of the answer. status moves to a final state, with its delivery events.

curl -s "$GALON_API_BASE/emails/<email id>" \
  -H "Authorization: Bearer $GALON_API_KEY"

With MCP: get_email

{"tool": "get_email", "arguments": {"id": "<email id>"}}

Next