All systems operational
v0.1.0-alpha
REST · gRPC · MCP · Webhooks · SDK · CLI

Every access mode. One unified platform.

Query mail, contacts, and scheduling from any layer of your stack. REST for direct integration, gRPC for real-time streaming, MCP for autonomous agents, and webhooks for event-driven architectures.

Provision API Key →
REST full CRUD over HTTPS OPENAPI SPEC INCLUDED
gRPC bidirectional streams HTTP/2 + PROTO BUFFERS
MCP 12 built-in tools STDIO TRANSPORT
<1ms webhook dispatch HMAC-SIGNED HTTP POST
100% HMAC verification EXACTLY-ONCE RELAY
// REST.API RFC 7231

Standard HTTP. Full CRUD. Predictable patterns.

Every Hermers resource ; messages, mailboxes, calendars, contacts, appointments, and tenants ; is accessible over a standard JSON REST API. Cursor-paginated, consistently structured, and fully typed.

GET/v1/mail/messagesList & filter messages
POST/v1/mail/sendSend a message
GET/v1/mail/mailboxesList mailboxes
POST/v1/calendar/eventsCreate a calendar event
GET/v1/contactsSearch contacts
POST/v1/scheduling/appointmentsBook an appointment
GET/v1/scheduling/availabilityFree-busy query
PATCH/v1/tenants/{id}Update tenant settings
DEL/v1/keys/{id}Revoke API key
DESIGN PRINCIPLES

Consistent. Predictable. Complete.

Every endpoint follows the same conventions so you never have to guess.

  • Cursor pagination on every list endpoint ; stable ordering across large datasets
  • Structured error bodies: machine-readable code, human-readable message, field-level detail
  • Full OpenAPI 3.1 spec ; import directly into Postman, Insomnia, or your API client
  • Official TypeScript SDK with full type coverage generated from the spec
  • Python SDK with Pydantic models and async support included
  • All responses include request IDs for tracing through to support
// GRPC.LAYER HTTP/2

Bidirectional streams. Sub-millisecond notification.

Connect over HTTP/2 for persistent bidirectional streams. Ideal for AI agents that require real-time mailbox notification, bulk mail processing pipelines, or continuous availability checking without polling overhead.

// GRPC SERVICES PROTO3
MailService
StreamMessages, SendMessage, GetMessage, ListMailboxes, MoveMessage, SetFlags
CalendarService
StreamEvents, GetAvailability, CreateEvent, UpdateEvent, DeleteEvent
ContactService
SearchContacts, GetContact, CreateContact, SyncFeed
SchedulingService
GetAvailability, CreateAppointment, CancelAppointment, StreamBookings
TenantService
GetTenant, UpdateQuota, RotateKey, ListAuditEvents
// GRPC STREAMING ; TYPESCRIPT TYPESCRIPT
import { HermesGrpc } from '@hermes/grpc';

const rpc = new HermesGrpc({
  endpoint: 'grpc.hermes.io:9000',
  apiKey: process.env.HERMES_KEY,
});

const stream = await rpc.mail
  .streamMessages({ mailbox: 'INBOX' });

for await (const msg of stream) {
  console.log(msg.id, msg.subject);
}
// Fires the instant a message is delivered.
// No polling, no backoff, no missed events.
Access via gRPC :9000 REST fallback
// MCP.LAYER ACTIVE

Give your AI the right tools. Nothing more.

Hermers ships a native MCP server over stdio transport. LLMs call structured tools against the mail, calendar, and scheduling graph ; without ever touching raw message content. Scoped API keys ensure agents can only access what they are explicitly authorized to see.

hermes_list_messages List and filter messages by mailbox, sender, date, or label. Returns metadata ; never raw body content.
hermes_get_message Retrieve the text content and headers of a specific message by ID, with attachments enumerated but not inlined.
hermes_send_message Compose and dispatch a message on behalf of an authorized mailbox. Requires the mail.write scope.
hermes_get_availability Query cross-platform free-busy across connected calendar feeds for one or more participants.
hermes_book_appointment Create and confirm an appointment. Fires iTIP REQUEST to all guests automatically. Requires cal.write scope.
hermes_search_contacts Prefix-search the contact graph by name, email, or organization. Returns structured vCard fields.
hermes_list_events List calendar events across a time window. Supports expansion of recurring events and multi-calendar merge.
hermes_list_appointments Retrieve upcoming bookings with guest RSVP statuses, service details, and confirmation state.
SECURITY MODEL

Agents can't exceed their key's scope.

Every MCP connection is authenticated by an API key. The key's scope array is the agent's permission boundary ; enforced at the transport layer, not the application layer.

  • mail.read ; list and retrieve messages. No send, no delete.
  • mail.write ; compose, send, and manage messages and mailboxes
  • cal.read ; read events and query availability. No create, no modify.
  • cal.write ; create, update, and cancel events and appointments
  • contacts.read ; search and retrieve contacts. No modification.
  • contacts.write ; create, update, and delete contacts
  • Strict permissions enforce tenant isolation even if a key is compromised
  • All tool invocations logged in the per-tenant audit trail
Access via MCP stdio REST equivalent gRPC equivalent
// WEBHOOKS STREAMING

Events delivered the millisecond they happen.

Subscribe to any event across mail, calendar, contacts, and scheduling. Every payload is HMAC-signed for verification and delivered via HTTP POST within milliseconds of commit. Automatic retry with exponential backoff and a full delivery audit trail.

// EVENT CATALOGUE 16 EVENTS
MAIL
mail.received mail.sent mail.bounced mail.flagged mail.moved mail.deleted
CALENDAR & SCHEDULING
calendar.event.created calendar.event.updated calendar.event.deleted appointment.created appointment.confirmed appointment.cancelled appointment.rescheduled guest.rsvp.updated
SYSTEM
tenant.plan.changed key.rotated
// DELIVERY GUARANTEES VERIFIED
Signing
Every payload signed with HMAC-SHA256. Verify with your webhook secret ; rotate it instantly from the console.
Delivery
Exactly-once semantics via transactional Kafka outbox. Events are committed atomically alongside the originating state change.
Retry
Exponential backoff with jitter up to 24 hours. Full delivery log with status, attempt count, and response body per event.
Latency
Sub-millisecond dispatch from commit to relay queue. Target delivery under 100ms on standard infrastructure.
Tracing
OpenTelemetry trace ID in every payload header. Correlate webhooks back to the originating API request end-to-end.
// SDK.LAYER OFFICIAL

Official SDKs. Works in CI/CD out of the box.

TypeScript and Python SDKs with full type coverage. The Hermers CLI handles tenant init, key provisioning, webhook registration, and local testing. Install once, use everywhere.

// PYTHON SDK PYTHON 3.10+
from hermes import Hermers
import asyncio

client = Hermers(api_key="K0X...")

async def check_inbox():
  messages = await client.mail.list(
    mailbox="INBOX",
    limit=20,
  )
  for msg in messages.data:
    print(msg.subject, msg.from_)

asyncio.run(check_inbox())
// CLI ; KEY & WEBHOOK MANAGEMENT BASH
# Register a webhook endpoint
$ hermes webhooks create
  --url https://app.io/hermes/hook
  --events mail.received appointment.confirmed
✓ Webhook W0Xc3d4... registered
Secret: whsec_... (store this now)

# Rotate a key instantly
$ hermes keys rotate K0X9a1b2c3
✓ Key rotated. Old key invalidated.
New key: K0Xd4e5f6... (0ms downtime)

# List active scopes on a key
$ hermes keys inspect K0X9a1b2c3
Scope: mail.read cal.write contacts.read
Last used: 2 minutes ago

// API KEY SCOPES

mail.read mail.write cal.read cal.write contacts.read contacts.write sched.read sched.write admin.keys admin.tenant admin.audit
// GET STARTED

Provision your first API key.

Initialize a tenant, create a scoped key, and make your first API call in under five minutes. Free tier includes REST and native protocol access.

Get API Keys →
// DOCUMENTATION

OpenAPI spec. SDK reference. Examples.

Full API reference, authentication guide, webhook integration walkthrough, and working code examples in TypeScript, Python, and Go.

Read the Docs →