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

Estimated time: 5 minutes.

## Before you start

- A sending domain verified in Galon Mail: see [Set up DNS for your sending domain](/cloud/docs/guides/set-up-dns-for-your-sending-domain).
- `curl` (or Python 3, or Node.js 18+).

## 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.](/cloud/docs/guides/media/send-your-first-email-1-activate.webp)

*Terms first, then the plan.*

## 2. Set your key

Create a key with **Send emails** ([Create an API key](/cloud/docs/guides/create-an-api-key)) and export it with the API base. Keep it server side.

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

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

**Expected output**

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

**With MCP: get_status**

```json
{"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.

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

```text
{
  "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.](/cloud/docs/guides/media/send-your-first-email-2-terminal.webp)

*The answer comes back at once: the email is a job, sent in the background.*

**With MCP: send_email**

```json
{"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.

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

**With MCP: get_email**

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

## Next

- [Send email over SMTP](/cloud/docs/guides/send-email-over-smtp)
- [Connect your AI coding agent (MCP)](/cloud/docs/guides/connect-your-ai-coding-agent)
- [API reference](/cloud/docs/api)
- [All guides](/cloud/docs/guides)
