Skip to content

api-reference.md

Latest commit

 

History

History
92 lines (67 loc) · 2.6 KB

api-reference.md

File metadata and controls

92 lines (67 loc) · 2.6 KB

API Reference

Auth and org

  • GET /auth/google/url
  • GET /auth/google/callback?code=...
  • POST /auth/refresh
  • POST /orgs
  • POST /orgs/invites
  • POST /orgs/invites/accept
  • POST /orgs/api-keys
    • create scoped organization API key

Admin read endpoints (Bearer auth)

  • GET /admin/organizations
  • GET /admin/domains?organization_id=<uuid>
  • GET /admin/mailboxes?organization_id=<uuid>
  • GET /admin/members?organization_id=<uuid>
  • GET /admin/invites?organization_id=<uuid>
  • GET /admin/api-keys?organization_id=<uuid>
  • GET /admin/webhooks?organization_id=<uuid>

Notes:

  • organization_id is optional; when omitted, the API resolves to the first organization the user belongs to.
  • Each endpoint verifies organization membership before returning data.

Mail client endpoints (Bearer auth)

  • GET /mail/mailboxes?organization_id=<uuid>
  • GET /mail/folders?mailbox_id=<uuid>
  • GET /mail/messages?folder_id=<uuid>&limit=50&offset=0
  • GET /mail/messages/{messageID}

Notes:

  • These endpoints return only resources the authenticated user can access through organization membership.
  • Message listing supports pagination via limit and offset.

Push notifications

  • POST /push/devices/register
    • register/update a user device token
    • platforms: fcm, apns
  • POST /push/send
    • send notification to a user’s active devices

Domain transfer

  • GET /domains/export?domain=example.com
    • returns ZIP backup
    • includes metadata JSON and .eml payload files where available
  • POST /domains/import?domain=example.com
    • multipart field: archive
    • imports ZIP backup into target domain

Security:

  • export/import now require both bearer auth and organization-domain access checks.

API-key provisioning and mail operations (/v1/*)

Auth:

  • X-API-Key: midemail_<prefix>_<secret>
    • or Authorization: ApiKey midemail_<prefix>_<secret>

Endpoints:

  • POST /v1/domains
    • create/update a domain for the API key’s organization
  • POST /v1/mailboxes
    • create/update mailbox in a domain
  • POST /v1/webhooks
    • register organization webhook URL and filters
  • POST /v1/mail/send
    • enqueue outbound mail payload
  • POST /v1/mail/receive
    • enqueue inbound mail payload

Autoconfig/autodiscover

  • GET /autoconfig?domain=example.com
  • GET /autoconfig.xml?domain=example.com
  • GET/POST /autodiscover/autodiscover.xml?emailaddress=user@example.com

Notes

  • Current API uses bearer JWT auth for protected routes.
  • /v1/* routes are API-key authenticated and scope-gated.
  • For large transfer operations, prefer async job wrapping in production deployments.