# Moonemail agent setup

Moonemail is an outbound transactional email API. It does not provide inboxes,
inbound email, SMTP relay or campaigns.

1. The owner creates a key with the minimum scopes for the requested task.
   Store it as MOONEMAIL_API_KEY in a secrets manager; never print or commit it.
2. Call GET /permissions with Authorization: Bearer $MOONEMAIL_API_KEY to discover
   granted scopes, expiry and sender-domain restriction. Respect any 403 denial;
   ask the owner for missing permissions instead of requesting full access.
3. Configure only resources needed by the owner's task, reading current state
   before changes. Write does not imply read or delete. Scopes are team-wide.
4. For sending, use a separate sending-access key restricted to a verified domain.
   Send a single test to an address the owner controls with POST /emails and a
   stable Idempotency-Key for retries. emails:read permits delivery inspection.
5. Report changes and remaining verification steps. A prompt is guidance; API
   permissions are enforced on the server.

Scopes:
- emails:send: POST /emails and /emails/batch.
- emails:read: GET /emails, /emails/:id and /emails/:id/events; includes message bodies and recipients.
- emails:update: PATCH /emails/:id and POST /emails/:id/cancel (scheduled messages).
- domains:read: GET /domains and /domains/:id (including DNS requirements).
- domains:write: POST /domains, PATCH /domains/:id and POST /domains/:id/verify.
- domains:delete: DELETE /domains/:id.
- webhooks:read: GET /webhooks, /webhooks/:id and /webhooks/:id/deliveries; no existing signing secrets.
- webhooks:write: POST /webhooks and PATCH /webhooks/:id. Can redirect team events;
  creating a hook returns its signing secret once. Store that secret securely.
- webhooks:delete: DELETE /webhooks/:id.
- suppressions:read: GET /suppressions (recipient addresses and reasons).
- suppressions:write: POST /suppressions.
- suppressions:delete: DELETE /suppressions/:email; permits sending again.

Create scoped keys with permission: scoped_access and an explicit scopes array.
Example: ["domains:read", "domains:write"] supports domain setup without deletion.
Scoped keys cannot manage API keys, team settings or payments. There are no
wildcards, implied grants or credential delegation. Existing full-access keys
remain supported but are not the recommended agent credential.
Domain restrictions apply only to send-only keys, never team-wide operational scopes.
GET /permissions is available to every valid key, including sending-only keys.

Publishing DNS requires separate authorization at the DNS provider. Domain
verification and SES production access are separate: verified domains do not
remove SES sandbox recipient restrictions. The platform onboarding sender can
send only to the account owner's address. Review readiness with the owner before
sending to customers. Payment changes require the account owner's dashboard session.