GET /emails
List the project's email log
API key (Bearer), on the public API endpoint.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
project_id | query | string | Required in a console session; ignored with an API key (the key's project). |
limit | query | integer | |
after | query | string | |
before | query | string | |
status | query | EmailJournalStatus | |
created_after | query | string | |
created_before | query | string | |
tag | query | string | |
to | query | string |
Responses
| Status | Description | Body |
|---|---|---|
200 | Log page | EmailJournalListResponse |
403 | Scopes mail:send and job:read required | |
422 | Invalid parameters | Error |
503 | mail_journal_unavailable |
Examples
curl
curl -X GET "$GALON_API_BASE/emails" \
-H "Authorization: Bearer $GALON_API_KEY"Node.js (SDK)
import { Galon } from "galon";
const galon = new Galon(process.env.GALON_API_KEY);
const result = await galon.emails.list({ limit: 20 });Python (SDK)
from galon import Galon
galon = Galon() # reads GALON_API_KEY
result = galon.emails.list({"limit": 20})POST /emails
Send a transactional email
Creates a job for 1 to 50 recipients (to, cc, bcc; to_email is still accepted for a single one). Each recipient receives their own copy with their unsubscribe link and counts towards the quota. Base64 attachments (at most 10, executables refused); the whole message is at most 25,000,000 bytes once encoded, attachments included (about 18 MB of files), otherwise 422 email_too_large before 202; scheduled_at defers sending by at most 72 h. No public SMTP, campaign or raw message. A job success means accepted for dispatch, not delivered.
API key (Bearer), on the public API endpoint.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string · required |
Request body
application/json · schema MailSend
| Field | Type | Description |
|---|---|---|
from_email | string · required | |
to_email | string | Legacy contract: a single recipient. Mutually exclusive with to. |
to | string | array<string> | One address or a list; to, cc and bcc combined: at most 50 distinct recipients. |
cc | array<string> | |
bcc | array<string> | Never revealed: each recipient receives their own copy. |
attachments | array<object> | At most 40 MB once encoded (MIME estimate); executable extensions, types and signatures refused. |
scheduled_at | string | ISO 8601 with time zone, at most 72 h ahead, at most 5 min in the past; rounded to the second (UTC). |
subject | string · required | |
text | string | |
html | string | |
reply_to | string | |
tags | object |
Responses
| Status | Description | Body |
|---|---|---|
202 | Sending queued (scheduled_at echoed if set) | EmailSendResponse |
403 | Scope mail:send missing | |
409 | Idempotency conflict | |
413 | Body larger than 42 MiB | |
422 | Invalid parameters | Error |
503 | job_projection_invalid: the server refuses to publish a result that does not satisfy its closed public schema | Error |
Examples
curl
curl -X POST "$GALON_API_BASE/emails" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Idempotency-Key: <unique-key>" \
-H "Content-Type: application/json" \
-d '{"from_email": "hello@acme.test", "to_email": "ana@client.test", "subject": "Bonjour", "html": "<p>Hi</p>"}'Node.js (SDK)
import { Galon } from "galon";
const galon = new Galon(process.env.GALON_API_KEY);
const result = await galon.emails.send({"from": "hello@acme.test", "to": "ana@client.test", "subject": "Bonjour", "html": "<p>Hi</p>"}, { idempotencyKey: "<unique-key>" });Python (SDK)
from galon import Galon
galon = Galon() # reads GALON_API_KEY
result = galon.emails.send({"from": "hello@acme.test", "to": "ana@client.test", "subject": "Bonjour", "html": "<p>Hi</p>"}, idempotency_key="<unique-key>")