Unified Email API

What Is a Unified Email API?

A unified email API is a single, standardized programming interface that lets your product read and write email data (messages, threads, folders, and drafts) across multiple mailbox providers without building a separate integration for each one.

Gmail and Outlook each expose their own APIs with different authentication flows, threading models, and rate limits. Knit normalizes these differences so your engineering team integrates once, and Knit handles the translation layer for every mailbox provider your customers use.

Knit normalizes four things across all providers:

How It Works

1. Your customer connects their mailbox
Knit's pre-built embedded auth UI handles OAuth and token management per provider. Your team writes zero auth code.

2. Knit normalizes the data
Messages, threads, folders, and drafts are all mapped to Knit's unified schema, regardless of how each provider stores or names them internally.

3. Your product calls one API
Use a single set of endpoints and data models across your entire product. Add a new mailbox provider later? No code changes on your side.

4. Stay in sync with real-time webhooks
Native and virtual webhooks fire on mailbox changes (a new message, a read/unread toggle, a moved thread) with a consistent event schema across all providers.

Email Data Objects

The following objects are available through the unified schema. All fields are normalized across providers.

Messages

Individual email messages with full recipient, body, and attachment detail.

id, messageType, subject, from[]: { name, email }, to[]: { name, email },
cc[]: { name, email }, bcc[]: { name, email }, replyTo[]: { name, email },
bodyText, bodyHTML, previewText, threadId, sentAt, receivedAt,
isUnread, isStarred, attachments[], folders[]

messageType distinguishes SENT from other message states. Filterable by from, to, cc, bcc, subject, unread, starred, hasAttachment, and received-date range.

→ Message data model · List messages · Get message by ID · Send message · Update message · Delete message

Threads

Conversation-level grouping of messages and drafts, with participant and attachment roll-ups.

id, latestDraftOrMessage: { ...Message }, hasAttachments, hasDrafts,
earliestMessageAt, latestMessageReceivedAt, latestMessageSentAt,
participants[]: { name, email }, previewText, starred, subject, unread,
messageIds[], draftIds[], folderIds[]

Filterable by subject, to, from, cc, bcc, folder, unread, starred, hasAttachment, and latest-message-date range.

→ Thread data model · List threads · Get thread by ID · Update thread · Delete thread

Folders

Mailbox folders, including system folders (Inbox, Sent) and nested custom folders.

id, name, parentId, childCount, singleLevel, systemFolder,
backgroundColor, textColor, totalCount, unreadCount

systemFolder distinguishes provider-default folders from user-created ones. Supports single-level or full multi-level hierarchy retrieval.

→ Folder data model · List folders · Get folder by ID · Create folder · Update folder · Delete folder

Drafts

Unsent messages saved to a mailbox, with the same recipient and attachment structure as sent messages.

id, subject, from[], to[], cc[], bcc[], body, attachments[], createdAt, updatedAt

→ Draft data model · List drafts · Get draft by ID · Create draft · Send draft · Update draft · Delete draft

Attachments

File attachments on messages, with separate metadata and content retrieval.

id, filename, contentType, size, contentId, isInline

→ Get attachment metadata by ID · Get attachment content by ID

API Reference

All email endpoints are organized by category. Each endpoint works identically regardless of the underlying provider. Pass your API key and the customer's X-Integration-Id, and the response schema is consistent across all providers.

Message APIs

Thread APIs

Folder APIs

Draft APIs

Attachment & Account APIs

Supported Platforms

Knit connects to Gmail and Outlook today.

This is narrower than some standalone email API providers, which also cover IMAP catch-all access and, in some cases, adjacent messaging channels. If your product needs a mailbox provider outside Gmail or Outlook, use the Connector Builder / Integration Agent to add it, or check back as Knit's supported list grows.

Key Capabilities

Real-Time Sync & Webhooks

Knit supports both native webhooks (forwarded directly from platforms that emit them) and virtual webhooks (Knit polls the source, detects changes, and emits events). Both use the same subscription interface and event schema, so your integration code is identical either way.

Supported event types include: record.new, record.modified, record.deleted, and more.

Zero Data Storage

Knit never stores your customers' emails at rest. Every API request passes through to the source mailbox in real time. This reduces your GDPR, CCPA, and SOC 2 compliance scope, since there are no replicated messages sitting in a third-party system.

Full Read/Write

Beyond reading messages and threads, the API supports composing and sending new messages, managing drafts end-to-end (create, update, send, delete), and organizing mail via folder CRUD.

AI Connector Builder / Integration Agent

When a customer's mailbox provider isn't in Knit's library, the AI Connector Builder lets your team define a new connector in hours. Specify the platform's API structure and data mapping; Knit's AI generates the connector.

Passthrough API

Need a field outside the unified APIs, like a Gmail-specific label color or an Outlook categorization field? Passthrough lets you make direct calls to the underlying mailbox provider using Knit's authentication layer.

MCP Compatibility

Knit is MCP-compatible, giving AI agents authenticated read/write access to messages, threads, and drafts across every connected mailbox through the same unified layer, with no per-provider auth or endpoint logic in your agent code.

Quick Start

Authentication

All requests require two headers:

Authorization: Bearer YOUR_API_KEY
X-Integration-Id: YOUR_CUSTOMER_INTEGRATION_ID

The X-Integration-Id is the unique identifier for a specific customer's connected mailbox, issued after they complete the Knit auth flow.

Fetch messages

curl --request GET \
     --url 'https://api.getknit.dev/v1.0/email.messages.list?unread=true&pageSize=20' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'X-Knit-Integration-Id: YOUR_CUSTOMER_INTEGRATION_ID'

Response: same schema whether the customer uses Gmail or Outlook:

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "MSG_123456789",
        "messageType": "SENT",
        "subject": "Re: Project Status Update - Q4 2026",
        "from": [{ "name": "John Smith", "email": "[email protected]" }],
        "to": [{ "name": "Sarah Johnson", "email": "[email protected]" }],
        "bodyText": "Hi Sarah, thank you for the detailed report...",
        "threadId": "THREAD_987654321",
        "sentAt": "2026-08-15T14:30:22Z",
        "receivedAt": "2026-08-15T14:30:25Z",
        "isUnread": false,
        "isStarred": true,
        "attachments": [
          { "id": "ATT_001", "filename": "Q4_Report.pdf", "contentType": "application/pdf", "size": 2048576, "isInline": false }
        ],
        "folders": [{ "id": "INBOX", "name": "Inbox" }]
      }
    ],
    "nextPageToken": "page_002"
  }
}

Send a message

curl --request POST \
     --url https://api.getknit.dev/v1.0/email.messages.send \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'X-Knit-Integration-Id: YOUR_CUSTOMER_INTEGRATION_ID' \
     --data '
{
  "subject": "Welcome aboard!",
  "to": [{ "email": "[email protected]", "name": "Customer" }],
  "body": "<p>Thanks for signing up, let'\''s get started.</p>"
}'

Create a draft

curl --request POST \
     --url https://api.getknit.dev/v1.0/email.drafts.create \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'X-Knit-Integration-Id: YOUR_CUSTOMER_INTEGRATION_ID'

Use Cases

Sales Engagement & Outreach Tools

Read and send email directly through a rep's own connected Gmail or Outlook mailbox, so outreach comes from a real inbox rather than a third-party sending domain, improving deliverability and reply-tracking.

Typical flow: fetch threads by participant → detect reply → update sequence status → send next-step message from the rep's mailbox

Unified Communication Timelines

Combine the Unified Email API with Knit's Unified CRM or Meeting API to build a single customer timeline spanning email threads, calls, and CRM activity.

Typical flow: fetch threads by contact email → fetch related meetings and CRM engagements → merge into one chronological timeline

Email-to-Task & CRM Automation

Turn incoming email into structured records (support tickets, CRM engagements, or tasks) without polling raw IMAP.

Typical flow: record.new webhook on message → parse and classify → create engagement or ticket via the relevant Knit API → mark message as read

AI Email Assistants & Copilots

Feed normalized message and thread data into LLM pipelines and MCP-compatible agents to build assistants that draft replies, summarize threads, or triage inboxes across whichever mailbox provider a customer uses.

Typical flow: sync messages + threads → embed into vector store → ground LLM draft generation in thread context → use MCP tools to create and send the reply

Compliance & eDiscovery Tooling

Pull message and thread history with attachment metadata for legal hold, audit, or compliance review workflows.

Typical flow: fetch messages by date range and participant → retrieve attachment metadata → export normalized record set for review

FAQ

What is a unified email API?
A unified email API is a single, standardized interface that lets your product read and write email (messages, threads, folders, and drafts) across multiple mailbox providers without building a separate integration for each one. You integrate with Knit once; Knit normalizes the data models, authentication, and API differences between providers.

Which mailbox providers does Knit support?
Gmail and Outlook today. This is narrower than some dedicated email API providers that also support generic IMAP or adjacent messaging channels. If your customers are on a provider outside Gmail or Outlook, check with Knit on roadmap or use the Connector Builder.

Can I send email through the API, or only read it?
Both. The API supports composing and sending new messages directly, as well as full draft management: create, update, send, and delete.

How long does it take to integrate?
Most teams go live in 1–3 days with Knit. Building a production-ready 1:1 native integration against a single provider like Gmail typically takes several weeks. When you build with Knit, one integration gives you access to every connected mailbox provider, and Knit maintains all connectors as providers update their APIs.

Does Knit store email content?
No. Knit is a pass-through layer: requests hit the source mailbox in real time and no message content is stored at rest. This reduces your GDPR, CCPA, and SOC 2 compliance scope.

How are threads different from messages in the unified schema?
A Thread groups related Messages and Drafts together with roll-up fields like hasAttachments, unread, and participants. Fetching a thread returns the latest message or draft inline (latestDraftOrMessage) along with the full list of message and draft IDs in the conversation.

Is Knit compatible with AI agents and MCP?
Yes. Knit is MCP-compatible, so agents in MCP-compatible frameworks can perform authenticated email read/write actions via Knit with no per-provider logic.

What's the passthrough API?
The passthrough API lets you make direct calls to the underlying mailbox provider using Knit's authentication layer. Use it for fields outside the unified schema.

Next Steps