Reference

API overview

The REST API: base URL, authentication, conventions, and the 17 operations shared by every client.

Base URL

https://api.goshenemail.com

All paths below are relative to it and versioned under /v1. The OpenAPI 3.1 document is served at /openapi.json and is the source the CLI schemas and MCP tool schemas are generated from.

Authentication

Every request carries Authorization: Bearer <key>, where the key is an account key (bze_) or a mailbox key (gme_). Each operation requires one scope, listed on its page. See Authentication.

Conventions

JSON in, JSON out. Request bodies are application/json. Responses are resource objects, not envelopes.
Identifiers in paths are URL encoded. inboxId is the inbox's email address; messageId is an RFC 5322 Message-ID with angle brackets. research@agents.goshenemail.com becomes research%40agents.goshenemail.com.
Arrays in queries repeat the name. ?labels=received&labels=unread.
Lists page with tokens. Pass nextPageToken back as pageToken. See Pagination.
Sends are idempotent. send and reply require an idempotencyKey; Idempotency-Key as a header also works. See Sending mail.
Errors are uniform. { "error": { "code", "message", "transient" } } with a 4xx or 5xx status. See Errors.
Times are ISO 8601 in UTC.

Operations

Inboxes

Operation	Method and path	Scope
List inboxes	`GET /v1/inboxes`	`inboxes:read`
Create an inbox	`POST /v1/inboxes`	`inboxes:write`
Get an inbox	`GET /v1/inboxes/{inboxId}`	`inboxes:read`
Update an inbox	`PATCH /v1/inboxes/{inboxId}`	`inboxes:write`
Delete an inbox	`DELETE /v1/inboxes/{inboxId}`	`inboxes:write`
Finish inbox setup	`POST /v1/inboxes/{inboxId}/setup`	`inboxes:write`

Messages

Operation	Method and path	Scope
List messages	`GET /v1/inboxes/{inboxId}/messages`	`messages:read`
Search messages	`GET /v1/inboxes/{inboxId}/messages/search`	`messages:read`
Get a message	`GET /v1/inboxes/{inboxId}/messages/{messageId}`	`messages:read`
Send a message	`POST /v1/inboxes/{inboxId}/messages/send`	`messages:send`
Reply to a message	`POST /v1/inboxes/{inboxId}/messages/{messageId}/reply`	`messages:send`
Update message labels	`PATCH /v1/inboxes/{inboxId}/messages/{messageId}/labels`	`messages:write`
Get an attachment	`GET /v1/inboxes/{inboxId}/messages/{messageId}/attachments/{attachmentId}`	`messages:read`

Threads

Operation	Method and path	Scope
List threads	`GET /v1/inboxes/{inboxId}/threads`	`messages:read`
Get a thread	`GET /v1/inboxes/{inboxId}/threads/{threadId}`	`messages:read`
Update thread labels	`PATCH /v1/inboxes/{inboxId}/threads/{threadId}/labels`	`messages:write`

Account

Operation	Method and path	Scope
Get usage	`GET /v1/usage`	`inboxes:read`

Validation

The OpenAPI schemas describe most constraints. The server also enforces a few that JSON Schema cannot express: a body (text or html) is required on sends, text plus html must fit in 512 KiB, attachments must fit in 2 MiB combined, and to plus cc plus bcc is capped at 50. Requests that fail validation return invalid_argument (422) with a message naming the field.

Other endpoints

GET /openapi.json: the contract.
POST /mcp: the hosted MCP server.
GET /healthz: liveness.

The /inbox-rpc/* and /rpc/* paths serve older clients and platform integrations and are not covered here.