Skip to main content
Glama
Sign In

email

by dev.primitive
OverviewDiscussionsAdmin

Read email attachment

getEmailAttachment
Read-onlyIdempotent

Read ONE attachment of an email. A text file (plain text, CSV, JSON, XML, Markdown, calendar and similar) comes back as text, HTML reduced to text; a PNG, JPEG, GIF or WebP image up to 1 MB as an image; any other file as base64 up to 256 KB, and larger ones only described. PDF and office documents are not converted to text. Name it by part_index or filename from the attachments getEmail returns; a single attachment needs neither. Long text comes max_chars at a time: when truncated is true, call again with offset set to next_offset. Result: email_id, source, part_index, filename, content_type, size_bytes, sha256, kind and content_available; for text, format, text, offset, returned_chars, total_chars, truncated and next_offset; for a small binary file, encoding and content_base64; for one too large, max_inline_bytes; and note when there is one.

Input Schema

NameRequiredDescriptionDefault
idYesID of the email the attachment belongs to.
offsetNoFor text: the character to start from. Use next_offset from the previous call to continue.
sourceNoWhether id is an email you received or one you sent.received
api_keyNoAPI key from createEmailAddress, used in place of sign-in.
filenameNoThe attachment's filename, when part_index is not to hand. Matched exactly, then ignoring case.
max_charsNoFor text: the most characters to return in this call.
part_indexNoThe attachment's part_index from the email's attachments list. Preferred over filename, which need not be unique.

Output Schema

NameRequiredDescriptionDefault
kindYesHow the content is returned.
noteNoWhat to tell the user, when there is something to say.
textNotext only: this part of the text.
formatNotext only: text_from_html when made from HTML.
offsetNotext only: character where this part starts.
sha256YesSHA-256 of the content, hex.
sourceYesWhich kind of email.
email_idYesEmail the attachment belongs to.
encodingNoSmall binary files: the encoding of content_base64.
filenameYesFile name; null when the email gave none.
truncatedNotext only: true when more text follows, at next_offset.
part_indexYesIts position in the email.
size_bytesYesSize in bytes, as the email declares it.
next_offsetNotext only: pass as offset to read on; absent at the end.
total_charsNotext only: length of the text; of the part read when the file was cut.
content_typeYesMedia type, such as text/csv.
content_base64NoSmall binary files: the content.
returned_charsNotext only: characters returned.
max_inline_bytesNoFiles too large to return: the largest size returned here, in bytes.
content_availableYesTrue when the content is in this result: in text, content_base64 or an image block.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • changedOutput schema / properties / encoding / description
      Previous value: -"Small binary files: base64, the encoding of content_base64."New value: +"Small binary files: the encoding of content_base64."
    • addedOutput schema / properties / encoding / enum
      Added value: +[
+  "base64"
+]
    • changedOutput schema / properties / format / description
      Previous value: -"text only: text, or text_from_html when made from HTML."New value: +"text only: text_from_html when made from HTML."
    • addedOutput schema / properties / format / enum
      Added value: +[
+  "text",
+  "text_from_html"
+]
    • changedOutput schema / properties / kind / description
      Previous value: -"text, image or binary."New value: +"How the content is returned."
    • addedOutput schema / properties / kind / enum
      Added value: +[
+  "text",
+  "image",
+  "binary"
+]
    • changedOutput schema / properties / source / description
      Previous value: -"received or sent: which kind of email."New value: +"Which kind of email."
    • addedOutput schema / properties / source / enum
      Added value: +[
+  "received",
+  "sent"
+]
  2. Changed8 schema fields changed
    • changedOutput schema / properties / encoding / description
      Previous value: -"Small binary files: the encoding of content_base64."New value: +"Small binary files: base64, the encoding of content_base64."
    • removedOutput schema / properties / encoding / enum
      Removed value: -[
-  "base64"
-]
    • changedOutput schema / properties / format / description
      Previous value: -"text only: text_from_html when made from HTML."New value: +"text only: text, or text_from_html when made from HTML."
    • removedOutput schema / properties / format / enum
      Removed value: -[
-  "text",
-  "text_from_html"
-]
    • changedOutput schema / properties / kind / description
      Previous value: -"How the content is returned."New value: +"text, image or binary."
    • removedOutput schema / properties / kind / enum
      Removed value: -[
-  "text",
-  "image",
-  "binary"
-]
    • changedOutput schema / properties / source / description
      Previous value: -"Which kind of email."New value: +"received or sent: which kind of email."
    • removedOutput schema / properties / source / enum
      Removed value: -[
-  "received",
-  "sent"
-]
  3. Changed8 schema fields changed
    • changedOutput schema / properties / encoding / description
      Previous value: -"Small binary files: base64, the encoding of content_base64."New value: +"Small binary files: the encoding of content_base64."
    • addedOutput schema / properties / encoding / enum
      Added value: +[
+  "base64"
+]
    • changedOutput schema / properties / format / description
      Previous value: -"text only: text, or text_from_html when made from HTML."New value: +"text only: text_from_html when made from HTML."
    • addedOutput schema / properties / format / enum
      Added value: +[
+  "text",
+  "text_from_html"
+]
    • changedOutput schema / properties / kind / description
      Previous value: -"text, image or binary."New value: +"How the content is returned."
    • addedOutput schema / properties / kind / enum
      Added value: +[
+  "text",
+  "image",
+  "binary"
+]
    • changedOutput schema / properties / source / description
      Previous value: -"received or sent: which kind of email."New value: +"Which kind of email."
    • addedOutput schema / properties / source / enum
      Added value: +[
+  "received",
+  "sent"
+]
  4. Changed26 schema fields changed
    • addedOutput schema / additionalProperties
      Added value: +false
    • changedOutput schema / description
      Previous value: -"Envelope; the attachment is in data."New value: +"One attachment: its description, and its content when it can be returned."
    • addedOutput schema / properties / content_available
      Added value: +{
+  "description": "True when the content is in this result: in text, content_base64 or an image block.",
+  "type": "boolean"
+}
    • addedOutput schema / properties / content_base64
      Added value: +{
+  "description": "Small binary files: the content.",
+  "type": "string"
+}
    • addedOutput schema / properties / content_type
      Added value: +{
+  "description": "Media type, such as text/csv.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • removedOutput schema / properties / data
      Removed value: -{
-  "description": "The attachment.",
-  "properties": {
-    "content_available": {
-      "description": "Content is included.",
-      "type": "boolean"
-    },
-    "content_base64": {
-      "description": "The file content.",
-      "type": "string"
-    },
-    "content_type": {
-      "description": "Media type.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "email_id": {
-      "description": "Email it belongs to.",
-      "type": "string"
-    },
-    "encoding": {
-      "description": "base64, for content_base64.",
-      "type": "string"
-    },
-    "filename": {
-      "description": "File name.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "format": {
-      "description": "text or text_from_html.",
-      "type": "string"
-    },
-    "kind": {
-      "description": "text, image or binary.",
-      "type": "string"
-    },
-    "max_inline_bytes": {
-      "description": "Largest inline size.",
-      "type": [
-        "number",
-        "string"
-      ]
-    },
-    "next_offset": {
-      "description": "Offset to read next.",
-      "type": [
-        "number",
-        "string"
-      ]
-    },
-    "note": {
-      "description": "What to tell the user.",
-      "type": "string"
-    },
-    "offset": {
-      "description": "Start of this part.",
-      "type": [
-        "number",
-        "string"
-      ]
-    },
-    "part_index": {
-      "description": "Its position in the email.",
-      "type": [
-        "number",
-        "string",
-        "null"
-      ]
-    },
-    "returned_chars": {
-      "description": "Characters returned.",
-      "type": [
-        "number",
-        "string"
-      ]
-    },
-    "sha256": {
-      "description": "Content hash.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "size_bytes": {
-      "description": "File size.",
-      "type": [
-        "number",
-        "string",
-        "null"
-      ]
-    },
-    "source": {
-      "description": "received or sent.",
-      "type": "string"
-    },
-    "text": {
-      "description": "This part of the text.",
-      "type": "string"
-    },
-    "total_chars": {
-      "description": "Text length; only the part read if the file was cut.",
-      "type": [
-        "number",
-        "string"
-      ]
-    },
-    "truncated": {
-      "description": "More at next_offset.",
-      "type": "boolean"
-    }
-  },
-  "type": "object"
-}
    • addedOutput schema / properties / email_id
      Added value: +{
+  "description": "Email the attachment belongs to.",
+  "type": "string"
+}
    • addedOutput schema / properties / encoding
      Added value: +{
+  "description": "Small binary files: base64, the encoding of content_base64.",
+  "type": "string"
+}
    • addedOutput schema / properties / filename
      Added value: +{
+  "description": "File name; null when the email gave none.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • addedOutput schema / properties / format
      Added value: +{
+  "description": "text only: text, or text_from_html when made from HTML.",
+  "type": "string"
+}
    • addedOutput schema / properties / kind
      Added value: +{
+  "description": "text, image or binary.",
+  "type": "string"
+}
    • addedOutput schema / properties / max_inline_bytes
      Added value: +{
+  "description": "Files too large to return: the largest size returned here, in bytes.",
+  "type": "integer"
+}
    • addedOutput schema / properties / next_offset
      Added value: +{
+  "description": "text only: pass as offset to read on; absent at the end.",
+  "type": "integer"
+}
    • addedOutput schema / properties / note
      Added value: +{
+  "description": "What to tell the user, when there is something to say.",
+  "type": "string"
+}
    • addedOutput schema / properties / offset
      Added value: +{
+  "description": "text only: character where this part starts.",
+  "type": "integer"
+}
    • addedOutput schema / properties / part_index
      Added value: +{
+  "description": "Its position in the email.",
+  "type": "integer"
+}
    • addedOutput schema / properties / returned_chars
      Added value: +{
+  "description": "text only: characters returned.",
+  "type": "integer"
+}
    • addedOutput schema / properties / sha256
      Added value: +{
+  "description": "SHA-256 of the content, hex.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • addedOutput schema / properties / size_bytes
      Added value: +{
+  "description": "Size in bytes, as the email declares it.",
+  "type": [
+    "integer",
+    "null"
+  ]
+}
    • addedOutput schema / properties / source
      Added value: +{
+  "description": "received or sent: which kind of email.",
+  "type": "string"
+}
    • removedOutput schema / properties / status
      Removed value: -{
-  "description": "HTTP status; 2xx on success.",
-  "type": "number"
-}
    • addedOutput schema / properties / text
      Added value: +{
+  "description": "text only: this part of the text.",
+  "type": "string"
+}
    • removedOutput schema / properties / tool
      Removed value: -{
-  "description": "Tool that answered.",
-  "type": "string"
-}
    • addedOutput schema / properties / total_chars
      Added value: +{
+  "description": "text only: length of the text; of the part read when the file was cut.",
+  "type": "integer"
+}
    • addedOutput schema / properties / truncated
      Added value: +{
+  "description": "text only: true when more text follows, at next_offset.",
+  "type": "boolean"
+}
    • changedOutput schema / required
      Previous value: -[
-  "tool",
-  "status",
-  "data"
-]New value: +[
+  "email_id",
+  "source",
+  "part_index",
+  "filename",
+  "content_type",
+  "size_bytes",
+  "sha256",
+  "kind",
+  "content_available"
+]
  5. Changed4 schema fields changed
    • changedInput schema / properties / api_key / description
      Previous value: -"Your API key from createEmailAddress, used in place of sign-in."New value: +"API key from createEmailAddress, used in place of sign-in."
    • changedOutput schema / properties / data / type
      Previous value: -[
-  "object",
-  "string",
-  "null"
-]New value: +"object"
    • changedOutput schema / properties / status / description
      Previous value: -"HTTP status."New value: +"HTTP status; 2xx on success."
    • addedOutput schema / properties / tool / description
      Added value: +"Tool that answered."
  6. Changed1 schema field changed
    • changedOutput schema / description
      Previous value: -"One attachment and its content."New value: +"Envelope; the attachment is in data."
  7. Changed11 schema fields changed
    • changedInput schema / properties / api_key / description
      Previous value: -"Key createEmailAddress returned. Send it when no account is signed in."New value: +"Your API key from createEmailAddress, used in place of sign-in."
    • changedInput schema / properties / source / description
      Previous value: -"Whether id is an inbound email (received, the default) or a sent email (sent)."New value: +"Whether id is an email you received or one you sent."
    • addedOutput schema / properties / data / properties / content_type / description
      Added value: +"Media type."
    • addedOutput schema / properties / data / properties / email_id / description
      Added value: +"Email it belongs to."
    • addedOutput schema / properties / data / properties / encoding / description
      Added value: +"base64, for content_base64."
    • addedOutput schema / properties / data / properties / filename / description
      Added value: +"File name."
    • addedOutput schema / properties / data / properties / part_index / description
      Added value: +"Its position in the email."
    • addedOutput schema / properties / data / properties / sha256 / description
      Added value: +"Content hash."
    • addedOutput schema / properties / data / properties / size_bytes / description
      Added value: +"File size."
    • addedOutput schema / properties / data / properties / text / description
      Added value: +"This part of the text."
    • addedOutput schema / properties / data / properties / total_chars / description
      Added value: +"Text length; only the part read if the file was cut."
  8. Changed1 schema field changed
    • changedInput schema / properties / api_key / description
      Previous value: -"The api_key from createEmailAddress, for a connection with no signed-in account. Leave it out when signed in."New value: +"Key createEmailAddress returned. Send it when no account is signed in."
  9. Changed14 schema fields changed
    • changedInput schema / properties / api_key / description
      Previous value: -"Only when no account is signed in: the api_key createEmailAddress returned, passed as is on every later call. Omit it when the user is signed in."New value: +"The api_key from createEmailAddress, for a connection with no signed-in account. Leave it out when signed in."
    • addedOutput schema / description
      Added value: +"One attachment and its content."
    • addedOutput schema / properties / data / description
      Added value: +"The attachment."
    • addedOutput schema / properties / data / properties / content_available / description
      Added value: +"Content is included."
    • addedOutput schema / properties / data / properties / content_base64 / description
      Added value: +"The file content."
    • addedOutput schema / properties / data / properties / format / description
      Added value: +"text or text_from_html."
    • addedOutput schema / properties / data / properties / kind / description
      Added value: +"text, image or binary."
    • addedOutput schema / properties / data / properties / max_inline_bytes / description
      Added value: +"Largest inline size."
    • addedOutput schema / properties / data / properties / next_offset / description
      Added value: +"Offset to read next."
    • addedOutput schema / properties / data / properties / note / description
      Added value: +"What to tell the user."
    • addedOutput schema / properties / data / properties / offset / description
      Added value: +"Start of this part."
    • addedOutput schema / properties / data / properties / returned_chars / description
      Added value: +"Characters returned."
    • addedOutput schema / properties / data / properties / source / description
      Added value: +"received or sent."
    • addedOutput schema / properties / status / description
      Added value: +"HTTP status."
  10. Changed2 schema fields changed
    • changedInput schema / properties / api_key / description
      Previous value: -"Primitive API key (prim_...). Only needed when this connection has no signed-in account: pass the api_key returned by createEmailAddress, unchanged, on every call for the rest of the conversation. Omit it when the user is signed in."New value: +"Only when no account is signed in: the api_key createEmailAddress returned, passed as is on every later call. Omit it when the user is signed in."
    • addedOutput schema / properties / data / properties / truncated / description
      Added value: +"More at next_offset."
  11. Changed5 schema fields changed
    • changedInput schema / properties / max_chars / description
      Previous value: -"For text: the most characters to return in this call (default 20000, at most 100000)."New value: +"For text: the most characters to return in this call."
    • removedOutput schema / additionalProperties
      Removed value: -false
    • addedOutput schema / properties / data / properties
      Added value: +{
+  "content_available": {
+    "type": "boolean"
+  },
+  "content_base64": {
+    "type": "string"
+  },
+  "content_type": {
+    "type": [
+      "string",
+      "null"
+    ]
+  },
+  "email_id": {
+    "type": "string"
+  },
+  "encoding": {
+    "type": "string"
+  },
+  "filename": {
+    "type": [
+      "string",
+      "null"
+    ]
+  },
+  "format": {
+    "type": "string"
+  },
+  "kind": {
+    "type": "string"
+  },
+  "max_inline_bytes": {
+    "type": [
+      "number",
+      "string"
+    ]
+  },
+  "next_offset": {
+    "type": [
+      "number",
+      "string"
+    ]
+  },
+  "note": {
+    "type": "string"
+  },
+  "offset": {
+    "type": [
+      "number",
+      "string"
+    ]
+  },
+  "part_index": {
+    "type": [
+      "number",
+      "string",
+      "null"
+    ]
+  },
+  "returned_chars": {
+    "type": [
+      "number",
+      "string"
+    ]
+  },
+  "sha256": {
+    "type": [
+      "string",
+      "null"
+    ]
+  },
+  "size_bytes": {
+    "type": [
+      "number",
+      "string",
+      "null"
+    ]
+  },
+  "source": {
+    "type": "string"
+  },
+  "text": {
+    "type": "string"
+  },
+  "total_chars": {
+    "type": [
+      "number",
+      "string"
+    ]
+  },
+  "truncated": {
+    "type": "boolean"
+  }
+}
    • addedOutput schema / properties / data / type
      Added value: +[
+  "object",
+  "string",
+  "null"
+]
    • removedOutput schema / properties / statusText
      Removed value: -{
-  "type": "string"
-}
  12. Added

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint/non-destructive, and the description layers on substantive behavior: which content types get converted to text, the 1 MB image and 256 KB binary inline limits, that oversize files are only described, and that long text is chunked with truncation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the per-type behavior, then attachment selection, then pagination, then return fields. Information-dense with almost no filler, though the single dense paragraph and the long result-field enumeration run together at the end.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read tool with full annotation coverage, complete schema, and an output schema, this description covers everything an agent needs: what is readable, size/format limits, how to pick the attachment, and how to page through long text. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: part_index is preferred over filename because filenames need not be unique, and offset/max_chars drive the continuation loop. It does not explain the api_key/source parameters, which live only in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read ONE attachment of an email') and immediately enumerates the per-type conversion behavior (text, image, base64, described-only). This clearly distinguishes it from getEmail, which lists attachments rather than reading them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete selection guidance: name the attachment by part_index or filename from getEmail's attachments list, and notes a single attachment needs neither; also explains the pagination loop via offset/next_offset. It signals a when-not implicitly ('PDF and office documents are not converted to text') but never names an alternative tool for those cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All email toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources