Tag many emails

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

{
  "integrations MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}

POST /local-emails/{caseId}/emails/tags

Access token

Adds tags to emails chosen by id, or to every email matching a search. By id, the tags are added right away; by search, a background job is queued and its id returned (see bulk-tag-jobs).

Path parameters

caseId string Required

application/json

Body Required

addMode string Required

Values are by_id or by_search.
tags array[string] Required

Tag ids or names to ADD (additive union). Names created in the case if absent.

At least 1 but not more than 100 elements.
ids array[string]

Target ids (required when addMode=by_id).

Not more than 500 elements.
search object

Search query (required when addMode=by_search).
Hide search attributes Show search attributes object
- page number
  
  Default value is 1.
- perPage number
  
  Default value is 10.
- skip number
  
  If skip/limit not provided, page/perPage will take precedence
- limit number
  
  If skip/limit not provided, page/perPage will take precedence
- sortOrder string
  
  Values are asc or desc. Default value is asc.
- searchText string
  
  Text search applied to all indexed fields (subject, body, snippet, from/to/cc/bcc). Supports the same AND / OR / NOT / -prefix, parentheses, "quoted phrases" and wildcards as the boolean query parser.
- folders array[string]
- domains array[string]
  
  Filter by participant domain(s) (part after @), any-of. Case-insensitive. Requires the domains field on the emailtext Atlas index.
- excludeDomains array[string]
  
  Exclude items whose domain(s) match any of these (any-of). Case-insensitive. Must not overlap domains.
- tags array[string]
- excludeTags array[string]
  
  Exclude items carrying any of these tag ids. Must not overlap tags.
- untagged boolean
  
  When truthy (1/true), return only emails with no tags attached. Takes precedence over the tags filter.
- participants array[string]
  
  Filter by participant email address(es), any-of.
- excludeEmails array[string]
  
  Exclude items whose participant address matches any of these (any-of). Must not overlap participants.
- startDate string(date-time)
  
  Only return emails whose date is at/after this instant (inclusive). Accepts an ISO-8601 date-time.
- endDate string(date-time)
  
  Only return emails whose date is at/before this instant (inclusive). Accepts an ISO-8601 date-time.
- sourceEmails array[string]
- sortBy string
  
  Values are date or subject. Default value is date.

Responses

200 application/json
Hide response attributes Show response attributes object
- data object Required
  
  Hide data attributes Show data attributes object
  
  mode string Required
  
  Values are by_id or by_search.
  
  status string Required
  
  'completed' for by_id; 'queued' for by_search.
  
  requested number
  
  matchedDocuments number
  
  skippedDocuments number
  
  resolvedTagIds array[string]
  
  attachmentsCreated number
  
  emailsMatched number
  
  by_id threads + autoTagEmails
  
  emailAttachmentsCreated number
  
  by_id threads + autoTagEmails
  
  jobId string
  
  by_search job id
- statusCode number Required
- timestamp string(date-time) Required

POST /local-emails/{caseId}/emails/tags

curl \
 --request POST 'http://api.example.com/local-emails/{caseId}/emails/tags' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "addMode": "by_id",
  "tags": [
    "string"
  ],
  "ids": [
    "string"
  ],
  "search": {
    "page": 1,
    "perPage": 10,
    "skip": 42.0,
    "limit": 42.0,
    "sortOrder": "asc",
    "searchText": "(discriminate OR racist) AND (\"Larry Graham\" OR Robinson)",
    "folders": [
      "string"
    ],
    "domains": [
      "string"
    ],
    "excludeDomains": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "excludeTags": [
      "string"
    ],
    "untagged": true,
    "participants": [
      "string"
    ],
    "excludeEmails": [
      "string"
    ],
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": "2024-12-31T23:59:59.999Z",
    "sourceEmails": [
      "string"
    ],
    "sortBy": "date"
  }
}'

Request examples

{
  "addMode": "by_id",
  "tags": [
    "string"
  ],
  "ids": [
    "string"
  ],
  "search": {
    "page": 1,
    "perPage": 10,
    "skip": 42.0,
    "limit": 42.0,
    "sortOrder": "asc",
    "searchText": "(discriminate OR racist) AND (\"Larry Graham\" OR Robinson)",
    "folders": [
      "string"
    ],
    "domains": [
      "string"
    ],
    "excludeDomains": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "excludeTags": [
      "string"
    ],
    "untagged": true,
    "participants": [
      "string"
    ],
    "excludeEmails": [
      "string"
    ],
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": "2024-12-31T23:59:59.999Z",
    "sourceEmails": [
      "string"
    ],
    "sortBy": "date"
  }
}

Response examples (200)

{
  "data": {
    "mode": "by_id",
    "status": "completed",
    "requested": 2,
    "matchedDocuments": 2,
    "skippedDocuments": 0,
    "resolvedTagIds": [
      "65a1b2c3d4e5f6a7b8c9d0a1"
    ],
    "attachmentsCreated": 2,
    "emailsMatched": 0,
    "emailAttachmentsCreated": 0,
    "jobId": "65a1b2c3d4e5f6a7b8c9d0f2"
  },
  "statusCode": 200,
  "timestamp": "2026-01-15T10:15:00.000Z"
}