GSW MAILBOX API / DOCUMENTATION

Your mailbox.
Your application.

Connect your application to email, calendar, contacts, files and AI through one mailbox API.

START BUILDING

Your first request

Create a connection and a server key in Control Center → API. Store the key as GSW_API_KEY in your application server’s secret settings.

A successful GET /connection returns the bound sender, connection mode, access and daily submission limit. Use the returned sender.id when submitting email.

CUSTOMER SETUP

Connect an external web app

1. Set up your GSW workspace.

   Sign in at GSW Mail. A workspace owner or administrator manages API access for the customer application.

2. Prepare the sending mailbox.

   Add and verify your domain, provision an active mailbox and finish its mailbox authorization. Live sending requires verified SPF, DKIM and DMARC. Admin sign-in alone does not authorize mailbox access.

3. Create a test connection.

   Open Control Center → API, give the connection your application’s name, choose its mailbox and leave Test mode enabled. Each connection binds to one mailbox.

4. Create and save a server key.

   The portal shows the secret once. Store it on your server; never put it in browser JavaScript, mobile bundles, URLs or a public repository. The current portal issues 30-day keys.

5. Integrate and verify.

   Call /connection, discover /capabilities, then exercise operations, email submissions and status polling in test mode.

6. Create a live connection.

   After verifying mailbox authorization and sender DNS, create a separate connection with Test mode unchecked and issue its key. Update your server secret and confirm a controlled live workflow. Test keys never turn into live keys automatically.

Authentication

Every private endpoint requires the same header. Access covers available functions for the bound mailbox; there are no per-operation scope selections or recipient allowlists.

Authorization: Bearer YOUR_SERVER_KEY

Keys cannot manage workspaces, domains/DNS, mailbox provisioning, billing, account credentials or API keys. Those controls stay in the administrator portal.

Connection & discovery

The public operation reference contains static schemas only. It exposes no mailbox records and does not authorize execution.

Mailbox operations

Use a single endpoint for the available mailbox functions. The catalog below is generated from the same operation registry used by the API. It reflects current coverage; a product UI feature may not yet have a registry operation.

{"name":"mail.list_recent","arguments":{"limit":10}}

Reads return the existing mailbox service result. For any operation marked Changes data, include an Idempotency-Key. Do not provide account, user or workspace context overrides: the server derives them from the connection.

Loading the operation catalog…

Send & track email

curl https://mail.guidedstepswellness.com/integrations/v1/emails \
  -H "Authorization: Bearer $GSW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inquiry-123-ack-v1" \
  -d '{"senderId":"MAILBOX_UUID","to":["visitor@example.org"],"subject":"Thank you","text":"We received your inquiry."}'

Replace MAILBOX_UUID with sender.id from /connection. Supported fields: required senderId, to, subject and text; optional html, replyTo and string-valued metadata.

202 means the submission was persisted. It does not prove inbox delivery. In test mode the response is simulated; in live mode it is accepted_for_processing.

AI chat, including Kimi

{"messages":[{"role":"user","content":"Draft a warm welcome message."}]}

Uses the connected mailbox’s enabled AI settings and selected provider, including Kimi. The API service must have KIMI_API_KEY configured. The response contains content and model; provider reasoning is not returned.

This endpoint generates text. Use mailbox operations for explicit actions such as sending or scheduling. Test connections return a simulated response without calling an AI provider.

Send 1–50 user/assistant messages, each up to 50,000 characters, within the 256 KiB request body limit.

Test mode & live verification

Test connections validate the integration contract and persist simulated email submissions. They do not execute mailbox operations, call AI providers or send mail. A simulated success does not verify the live mailbox authorization or provider account.

1. Verify /connection reports the expected mailbox and mode.
2. Retrieve /capabilities and verify operation schemas.
3. Submit an email in test mode, poll its ID and retry the same payload/key. Confirm the ID is unchanged.
4. Use a live connection to run a mailbox read. Verify AI with a small prompt if enabled.
5. For sending, use a controlled recipient and verify processing status and receipt. Investigate uncertain submissions before sending again.

In Control Center, Run mailbox and AI checks verifies a real mailbox read and the selected AI provider with the existing admin-authorized mailbox. It creates no external key and sends no email. It is a service diagnostic; it does not replace bearer-key and delivery verification.

Errors, limits & safe retries

{"error":{"code":"invalid_api_key","requestId":"req-123","retryable":false}}

Idempotency keys are 1–200 characters using letters, numbers, periods, underscores, colons or hyphens. Direct-email retries return the original submission. Operation write retries return execution status and a resource reference, not the full original result. An in-progress or unknown result requires investigation before another write.

The default direct-email limit is 100 submissions per connection per UTC day; inspect /connection for its configured value. Mailbox operations have their own service validations and sending limits.

Manage access over time

Rotate keys before expiry: create a replacement, update your application’s secret, verify a request and revoke the previous key. Pause a connection or revoke its keys in Control Center to stop subsequent authorization.

Already accepted external actions cannot be recalled. Schedules and automations created through a connection have their own lifecycle; pause or delete them separately when retiring a workflow. If mailbox authorization expires or is revoked, sign in as the mailbox owner and use Restore mailbox service access. Older authorizations created before encrypted credential storage require this one-time renewal; token hashes cannot be recovered as credentials.