MAILRAFT / PRODUCT

Developers

MailRaft exposes a stable REST surface and an MCP gateway so developers can embed the product into their own tooling under scoped tokens, without ever exposing provider credentials in a browser.

Base URLs

• Dashboard: https://app.mailraft.com
• API: https://api.mailraft.com (GET /health is public)
• Docs: https://docs.mailraft.com (versioned at /v1/)
• Status: https://status.mailraft.com

Authentication

• Scoped MailRaft bearer keys issued through authenticated Developer settings.
• Keys never carry provider credentials and are revocable immediately.
• The raw key is shown exactly once at creation and stored as a high-entropy hash.
• Browser mutation also requires a session CSRF token on app.mailraft.com.

REST endpoints

• GET /v1/integrations - list configured integrations
• POST /v1/integrations - create a scoped integration
• GET /v1/integrations/:id - read an integration
• PATCH /v1/integrations/:id - update scope-safe fields
• DELETE /v1/integrations/:id - revoke immediately
• POST /v1/integrations/:id/test - bounded probe only
• GET /v1/integrations/:id/calls - audited call history
• POST /v1/integrations/:id/execute - run an action under policy

Scopes

• integrations:read for GET and audit routes
• integrations:execute for test and execute
• integrations:manage for create, patch and revoke
• API-key scopes do not override integration action scopes, current membership, tenant status or plan limits

MCP gateway

The stdio MCP gateway exposes a focused tool set that uses the same policy layer as the REST API. Each invocation rechecks membership, scopes, quotas and revocation through /v1/call.

• mailraft_list_messages, mailraft_read_message
• mailraft_create_draft, mailraft_request_send
• mailraft_list_integrations, mailraft_test_integration, mailraft_call_integration
• mailraft_get_operation
• mailraft_list_leads, mailraft_prepare_campaign (campaigns return pending_approval)

Safety invariants

• No action can self-approve. Approval binds exact content; any edit invalidates it.
• Unknown transport outcomes are reconciled on provider ID, never blindly retried.
• Call history is sanitized; secrets, cookies and provider payloads never appear in audit records.
• Rate limits are enforced per tenant and per API key.

Webhooks

• GET /webhooks/integrations/:id verifies a Meta-style challenge.
• POST /webhooks/integrations/:id verifies HMAC signatures over the raw bounded body (256 KiB) before parsing.
• POST /webhooks/ses validates SNS signatures against the exact SES SNS certificate host.
• All webhook events emit a sanitized audit row with rejection_code and signature_verdict (never raw payloads).

Error model

• 400 for validation and malformed input.
• 401 for missing or invalid credentials.
• 403 for scope or membership denial.
• 404 for foreign objects.
• 409 for integration_busy (overlapping execution).
• 429 for rate limit; retry with Retry-After.
• 5xx responses carry a request_id for support.

Full guides

See https://docs.mailraft.com/v1/api, https://docs.mailraft.com/v1/mcp and https://docs.mailraft.com/v1/webhooks for versioned reference documentation.

SDKs and clients

During the beta, use plain HTTP and the published OpenAPI document. Official SDKs ship after the API shape has been stable for 90 days.

Changelog

The /v1/ prefix pins the stable API surface. Breaking changes land under a new version prefix; deprecations stay dual-run for a documented grace period.