List attachments

Returns metadata for the attachments on a message — names, content types, and sizes. Does not return file content; use Download an attachment to download bytes.

GET/api/v1/messages/{messageId}/attachments

Auth: Bearer API key — requires messages:read scope
Async: No
Pagination: No — full list returned in one response

Authorization

The API key must include the messages:read scope, and have the message’s mailbox in its allowlist. A missing scope returns 403; a mailbox outside the allowlist returns 404.

Path parameters

messageIdstring

The message identifier. Available from the webhook and from messageId in Received Message Detail responses.

Response

{
  "attachments": [
    {
      "id":             "AAMkADk5...",
      "name":           "invoice.pdf",
      "contentType":    "application/pdf",
      "size":           245678,
      "attachmentType": "fileAttachment"
    }
  ]
}

Attachment object

idstring

Attachment identifier. Pass this to the download endpoint.

namestring

Original filename.

contentTypestring

MIME type.

sizeinteger

Size in bytes.

attachmentType"fileAttachment" | "referenceAttachment" | "itemAttachment"

The attachment kind. Only fileAttachment can be downloaded; others (referenceAttachment, itemAttachment) are listed for completeness but cannot be retrieved through the download endpoint.

Request

curl 'https://c1.emailgistics.com/api/v1/messages/AAMkAGI2NjY1ZTM3.../attachments' \
  -H 'Authorization: Bearer YOUR_API_KEY'

A common integration is: receive a webhook, list attachments, decide which to download. The fields below come from the webhook payload; payload["id"] is the same value this endpoint accepts as messageId.

def handle_webhook(payload):
    if not payload["hasAttachments"]:
        return {"status": "success", "message": "No attachments to process"}

    message_id = payload["id"]
    attachments = http_get(
        f"https://c1.emailgistics.com/api/v1/messages/{message_id}/attachments",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )["attachments"]

    pdfs = [a for a in attachments
            if a["attachmentType"] == "fileAttachment"
            and a["contentType"] == "application/pdf"]

    for pdf in pdfs:
        process(pdf["id"], pdf["name"])

    return {"status": "success", "message": f"Queued {len(pdfs)} PDFs."}

Errors

Status	When
`401`	API key missing, malformed, or expired.
`403`	Key is missing the `messages:read` scope.
`404`	`messageId` is unknown, or the message’s mailbox is not in the key’s allowlist (the two cases are indistinguishable).
`429`	Rate limit exceeded — see Rate limits.
`5xx`	Transient upstream issue (typically the underlying Exchange tenant).

Error bodies follow the standard shape — see Errors.

Notes

Attachment content is fetched on demand from the customer’s Exchange tenant; nothing is stored on Emailgistics servers.

Download an attachment — fetch the bytes.
Received Message Detail — find messageId values.
Webhook request payload — receive messageId for incoming messages.