integrations

Start an email import

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://docs.usehearsay.com/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "integrations MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}
Close
POST /email-data/{caseId}/start-import-emails
Access token

Queues a job that imports emails from a linked mailbox into the case: chosen threads, the results of one or several searches, or everything (optionally limited to some folders). Returns the job; poll GET import-jobs/:jobId for progress. An extraction-code user may only name a mailbox linked to their own code (404 otherwise).

Path parameters

  • caseId string Required
application/json

Body Required

  • providerId string Required
  • extractionCode string Required
  • notificationEmails array[string]

    Additional email addresses to send email to when export completes (other than user email)

  • type string

    Values are by_thread, by_search, import_all, or by_multi_query. Default value is by_thread.

  • emails array[object]
    Hide emails attribute Show emails attribute object
    • threadId string Required
  • searchData object
    Hide searchData attributes Show searchData attributes object
    • anyEmail array[string]
    • to array[string]
    • bcc array[string]
    • cc array[string]
    • from array[string]
    • hasAttachment boolean
    • receivedAfter string
    • receivedBefore string
    • keywords array[string]
    • subject string
    • contactNames array[string]
    • folders array[string]

      Restrict the search to these folders (folder id/path as returned by fetch-folders). Optional; when omitted, all non-system folders are searched.

  • multiQueryData object
    Hide multiQueryData attributes Show multiQueryData attributes object
    • queries array[string]

      Raw Gmail boolean query strings (e.g. "a OR b OR c", "x AND (y OR z)"). Passed verbatim to Gmail q=, with date range appended.

    • emails array[string]

      Email addresses to search for as any participant. Each address is expanded into (from:e OR to:e OR cc:e OR bcc:e) and run as its own query.

    • dateStart string

      Optional inclusive lower bound of received date for all queries (ISO date). Omit for no lower bound.

    • dateEnd string

      Optional inclusive upper bound of received date for all queries (ISO date). Omit for no upper bound.

  • folderIds array[string]

    Restrict the import to these provider folders (folder id as returned by fetch-folders). Optional. Applies to import_all, by_search and by_multi_query; ignored for by_thread.

  • importAllSkipPages number

    Number of pages to skip for import all

  • scheduledFor string

    If set, schedule the import to start at this time instead of immediately. Must be in the future.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • data object Required
      Hide data attributes Show data attributes object
      • createdAt string(date-time) Required
      • updatedAt string(date-time) Required
      • id string Required
      • emailDataProvider object | null Required

        Not loaded by any route, so always null.

      • extractionCode object | null Required

        Not loaded by any route, so always null.

      • case object | null Required

        Not loaded by any route, so always null.

      • notificationEmails array[string] Required
      • status string Required

        Values are not_started, in_progress, completed, or failed.

      • type string Required

        Values are by_thread, by_search, import_all, or by_multi_query.

      • startedAt string(date-time) | null Required
      • completedAt string(date-time) | null Required
      • failedAt string(date-time) | null Required
      • message string | null Required
      • jobData object | null Required
      • importedThreadsCount number Required
      • importedEmailsCount number Required
      • totalThreadsCount number Required
      • totalEmailsCount number Required
      • isCancelled boolean Required
      • scheduledFor string(date-time) | null
    • statusCode number Required
    • timestamp string(date-time) Required
POST /email-data/{caseId}/start-import-emails 
curl \
 --request POST 'http://api.example.com/email-data/{caseId}/start-import-emails' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "providerId": "string",
  "extractionCode": "string",
  "notificationEmails": [
    "string"
  ],
  "type": "by_thread",
  "emails": [
    {
      "threadId": "string"
    }
  ],
  "searchData": {
    "anyEmail": [
      "string"
    ],
    "to": [
      "string"
    ],
    "bcc": [
      "string"
    ],
    "cc": [
      "string"
    ],
    "from": [
      "string"
    ],
    "hasAttachment": true,
    "receivedAfter": "string",
    "receivedBefore": "string",
    "keywords": [
      "string"
    ],
    "subject": "string",
    "contactNames": [
      "string"
    ],
    "folders": [
      "string"
    ]
  },
  "multiQueryData": {
    "queries": [
      "string"
    ],
    "emails": [
      "string"
    ],
    "dateStart": "string",
    "dateEnd": "string"
  },
  "folderIds": [
    "string"
  ],
  "importAllSkipPages": 42.0,
  "scheduledFor": "string"
}'
Request examples 
{
  "providerId": "string",
  "extractionCode": "string",
  "notificationEmails": [
    "string"
  ],
  "type": "by_thread",
  "emails": [
    {
      "threadId": "string"
    }
  ],
  "searchData": {
    "anyEmail": [
      "string"
    ],
    "to": [
      "string"
    ],
    "bcc": [
      "string"
    ],
    "cc": [
      "string"
    ],
    "from": [
      "string"
    ],
    "hasAttachment": true,
    "receivedAfter": "string",
    "receivedBefore": "string",
    "keywords": [
      "string"
    ],
    "subject": "string",
    "contactNames": [
      "string"
    ],
    "folders": [
      "string"
    ]
  },
  "multiQueryData": {
    "queries": [
      "string"
    ],
    "emails": [
      "string"
    ],
    "dateStart": "string",
    "dateEnd": "string"
  },
  "folderIds": [
    "string"
  ],
  "importAllSkipPages": 42.0,
  "scheduledFor": "string"
}
Response examples (200) 
{
  "data": {
    "createdAt": "2026-01-15T14:30:00.000Z",
    "updatedAt": "2026-01-15T14:30:00.000Z",
    "id": "507f1f77bcf86cd799439011",
    "emailDataProvider": {},
    "extractionCode": {},
    "case": {},
    "notificationEmails": [
      "jane.doe@example.com"
    ],
    "status": "not_started",
    "type": "by_thread",
    "startedAt": "2026-01-15T14:30:00.000Z",
    "completedAt": "2026-05-04T09:42:00Z",
    "failedAt": "2026-05-04T09:42:00Z",
    "message": "Importing threads",
    "jobData": {
      "providerId": "65a1b2c3d4e5f6a7b8c9d0e1"
    },
    "importedThreadsCount": 120,
    "importedEmailsCount": 348,
    "totalThreadsCount": 400,
    "totalEmailsCount": 1150,
    "isCancelled": false,
    "scheduledFor": "2026-05-04T09:42:00Z"
  },
  "statusCode": 200,
  "timestamp": "2026-01-15T10:15:00.000Z"
}