Get attachment
Namespace: microsoft.graph
Important
APIs under the /beta
version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Read the properties, relationships, or raw contents of an attachment that is attached to a user event, message, Outlook task, or group post.
Caution
Outlook tasks is deprecated and stopped returning data on August 10, 2022. Update existing apps that use this feature with Outlook tasks.
An attachment can be one of the following types:
- A file. Programmatically, this is a fileAttachment resource. See example 1.
- An Outlook item (contact, event or message). Programmatically, an item attachment is an itemAttachment resource. You can use
$expand
to further get the properties of that item, including any nested attachments up to 30 levels. See example 3 and example 4. - A link to a file stored in the cloud. Programmatically, this is a referenceAttachment resource. See example 5.
All these types of attachments are derived from the attachment resource.
This API is available in the following national cloud deployments.
Global service | US Government L4 | US Government L5 (DOD) | China operated by 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Get the raw contents of a file or item attachment
You can append the path segment /$value
to get the raw contents of a file or item attachment.
For a file attachment, the content type is based on its original content type. See an example 6.
For an item attachment that is a contact, event, or message, the raw contents returned is in MIME format.
Item attachment type | Raw contents returned |
---|---|
contact | vCard MIME format. See example 7. |
event | iCal MIME format. See example 8. |
message | MIME format. See example 9. |
Attempting to get the $value
of a reference attachment returns HTTP 405.
Note
When certain files are requested, MIME can encode the byte stream output in the response and provide a link to download the file as an email attachment.
Permissions
Depending on the resource (event, message, outlookTask, or post) that the attachment is attached to and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. To learn more, including taking caution before choosing more privileged permissions, search for the following permissions in Permissions.
Supported resource | Delegated (work or school account) | Delegated (personal Microsoft account) | Application |
---|---|---|---|
event | Calendars.Read | Calendars.Read | Calendars.Read |
message | Mail.Read | Mail.Read | Mail.Read |
outlookTask | Tasks.Read | Tasks.Read | Not supported |
post | Group.Read.All | Not supported | Not supported |
HTTP request
This section shows the HTTP GET request syntax for each of the entities (event, message, Outlook task, and post) that support attachments:
- To get the properties and relationships of an attachment, specify the attachment ID to index into the attachments collection, attached to the specified event, message, Outlook task, or post instance.
- If the attachment is a file or Outlook item (contact, event, or message), you can further get the raw contents of the attachment by appending the path segment
/$value
to the request URL.
An attachment of an event:
GET /me/events/{id}/attachments/{id}
GET /users/{id | userPrincipalName}/events/{id}/attachments/{id}
GET /me/events/{id}/attachments/{id}/$value
GET /users/{id | userPrincipalName}/events/{id}/attachments/{id}/$value
An attachment of a message in a user's mailbox:
GET /me/messages/{id}/attachments/{id}
GET /users/{id | userPrincipalName}/messages/{id}/attachments/{id}
GET /me/messages/{id}/attachments/{id}/$value
GET /users/{id | userPrincipalName}/messages/{id}/attachments/{id}/$value
An attachment of a message contained in a top level mailFolder in a user's mailbox:
GET /me/mailFolders/{id}/messages/{id}/attachments/{id}
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages/{id}/attachments/{id}
GET /me/mailFolders/{id}/messages/{id}/attachments/{id}/$value
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages/{id}/attachments/{id}/$value
An attachment of a message contained in a child folder of a mailFolder in a user's mailbox:
GET /me/mailFolders/{id}/childFolders/{id}/.../messages/{id}/attachments/{id}
GET /users/{id | userPrincipalName}/mailFolders/{id}/childFolders/{id}/messages/{id}/attachments/{id}
GET /me/mailFolders/{id}/childFolders/{id}/.../messages/{id}/attachments/{id}/$value
GET /users/{id | userPrincipalName}/mailFolders/{id}/childFolders/{id}/messages/{id}/attachments/{id}/$value
The preceding example shows one level of nesting, but a message can be located in a child of a child and so on.
An attachment of an Outlook task:
GET /me/outlook/tasks/{id}/attachments/{id}
GET /users/{id}/outlook/tasks/{id}/attachments/{id}
GET /me/outlook/tasks/{id}/attachments/{id}/$value
GET /users/{id}/outlook/tasks/{id}/attachments/{id}/$value
An attachment of a post in a thread belonging to a conversation of a group:
GET /groups/{id}/threads/{id}/posts/{id}/attachments/{id}
GET /groups/{id}/conversations/{id}/threads/{id}/posts/{id}/attachments/{id}
GET /groups/{id}/threads/{id}/posts/{id}/attachments/{id}/$value
GET /groups/{id}/conversations/{id}/threads/{id}/posts/{id}/attachments/{id}/$value
Optional query parameters
This method supports some of the OData Query Parameters to help customize the response.
Use $expand
to get the properties of an item attachment (contact, event, or message). See example 3 and example 4.
Request headers
Name | Type | Description |
---|---|---|
Authorization | string | Bearer {token}. Required. Learn more about authentication and authorization. |
Request body
Don't supply a request body for this method.
Response
If successful, the GET method returns a 200 OK
response code.
If you're getting the properties and relationships of an attachment, the response body includes an attachment object. The properties of that type of attachment are returned: fileAttachment, itemAttachment, or referenceAttachment.
If you're getting the raw contents of a file or item attachment, the response body includes the raw value of the attachment.
Examples
Example 1: Get the properties of a file attachment
Request
The following example shows a request to get the properties of a file attachment on a message.
GET https://graph.microsoft.com/beta/me/messages/AAMkAGUzY5QKjAAA=/attachments/AAMkAGUzY5QKjAAABEgAQAMkpJI_X-LBFgvrv1PlZYd8=
Response
The following example shows the response. Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('bb8775a4-4d8c-42cf-a1d4-4d58c2bb668f')/messages('AAMkAGUzY5QKjAAA%3D')/attachments/$entity",
"@odata.type": "#microsoft.graph.fileAttachment",
"id": "AAMkAGUzY5QKjAAABEgAQAMkpJI_X-LBFgvrv1PlZYd8=",
"lastModifiedDateTime": "2019-04-02T03:41:29Z",
"name": "Draft sales invoice template.docx",
"contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"size": 13068,
"isInline": false,
"contentId": null,
"contentLocation": null,
"contentBytes": "UEsDBBQABgAIAAAAIQ4AAAAA"
}
Example 2: Get the properties of an item attachment
Request
The next example shows how to get an item attachment on a message. The properties of the itemAttachment are returned.
GET https://graph.microsoft.com/beta/me/messages/AAMkADA1M-zAAA=/attachments/AAMkADA1M-CJKtzmnlcqVgqI=
Response
The following example shows the response. Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#users('d1a2fae9-db66-4cc9-8133-2184c77af1b8')/messages('AAMkADA1M-zAAA%3D')/attachments/$entity",
"@odata.type":"#microsoft.graph.itemAttachment",
"id":"AAMkADA1M-CJKtzmnlcqVgqI=",
"lastModifiedDateTime":"2017-07-21T00:20:34Z",
"name":"Reminder - please bring laptop",
"contentType":null,
"size":32005,
"isInline":false
}
Example 3: Expand and get the properties of the item attached to a message
Request
The next example shows how to use $expand
to get the properties of the item (contact, event, or message) that is attached to the message. In this example, that item is
a message; the properties of that attached message are also returned.
GET https://graph.microsoft.com/beta/me/messages/AAMkADA1M-zAAA=/attachments/AAMkADA1M-CJKtzmnlcqVgqI=/?$expand=microsoft.graph.itemattachment/item
Response
The following example shows the response. Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#users('d1a2fae9-db66-4cc9-8133-2184c77af1b8')/messages('AAMkADA1M-zAAA%3D')/attachments/$entity",
"@odata.type":"#microsoft.graph.itemAttachment",
"id":"AAMkADA1MCJKtzmnlcqVgqI=",
"lastModifiedDateTime":"2017-07-21T00:20:34Z",
"name":"Reminder - please bring laptop",
"contentType":null,
"size":32005,
"isInline":false,
"item":{
"@odata.type":"#microsoft.graph.message",
"id":"",
"createdDateTime":"2017-07-21T00:20:41Z",
"lastModifiedDateTime":"2017-07-21T00:20:34Z",
"receivedDateTime":"2017-07-21T00:19:55Z",
"sentDateTime":"2017-07-21T00:19:52Z",
"hasAttachments":false,
"internetMessageId":"<BY2PR15MB05189A084C01F466709E414F9CA40@BY2PR15MB0518.namprd15.prod.outlook.com>",
"subject":"Reminder - please bring laptop",
"bodyPreview": "PFA\r\n\r\nThanks,\r\nRob",
"importance":"normal",
"conversationId":"AAQkADA1MzMyOGI4LTlkZDctNDkzYy05M2RiLTdiN2E1NDE3MTRkOQAQAMG_NSCMBqdKrLa2EmR-lO0=",
"conversationIndex":"AQHTAbcSwb41IIwGp0qstrYSZH+U7Q==",
"isDeliveryReceiptRequested":false,
"isReadReceiptRequested":false,
"isRead":false,
"isDraft":false,
"webLink":"https://outlook.office365.com/owa/?ItemID=AAMkADA1M3MTRkOQAAAA%3D%3D&exvsurl=1&viewmodel=ReadMessageItem",
"internetMessageHeaders": [ ],
"body":{
"contentType":"html",
"content":"<html><head>\r\n</head>\r\n<body>\r\n</body>\r\n</html>"
},
"sender":{
"emailAddress":{
"name":"Adele Vance",
"address":"AdeleV@contoso.com"
}
},
"from":{
"emailAddress":{
"name":"Adele Vance",
"address":"AdeleV@contoso.com"
}
},
"toRecipients":[
{
"emailAddress":{
"name":"Alex Wilbur",
"address":"AlexW@contoso.com"
}
}
],
"ccRecipients":[
{
"emailAddress":{
"name":"Adele Vance",
"address":"AdeleV@contoso.com"
}
}
],
"flag":{
"flagStatus":"notFlagged"
}
}
}
Example 4: Expand and get the properties of an item attached to a message, including any attachment to the item
Request
The next example uses the same request as in example 3 to get the properties of an item attachment on a message by using $expand
. In this case, because the attached item also has a file attachment, the response includes the properties of the file attachment as well.
GET https://graph.microsoft.com/beta/me/messages/AAMkADA1M-zAAA=/attachments/AAMkADA1M-CJKtzmnlcqVgqI=/?$expand=microsoft.graph.itemattachment/item
Response
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('d1a2fae9-db66-4cc9-8133-2184c77af1b8')/messages('AAMkADA1M-zAAA%3D')/attachments(microsoft.graph.itemAttachment/item())/$entity",
"@odata.type": "#microsoft.graph.itemAttachment",
"id": "AAMkADA1MCJKtzmnlcqVgqI=",
"lastModifiedDateTime": "2021-01-06T13:28:11Z",
"name": "Nested Message With Attachment",
"contentType": null,
"size": 465916,
"isInline": false,
"item": {
"@odata.type": "#microsoft.graph.message",
"id": "",
"createdDateTime": "2021-01-06T13:28:30Z",
"lastModifiedDateTime": "2021-01-06T13:27:40Z",
"receivedDateTime": "2021-01-06T13:27:25Z",
"sentDateTime": "2021-01-06T13:27:04Z",
"hasAttachments": true,
"internetMessageId": "<BY2PR15MB05189A084C01F466709E414F9CA40@BY2PR15MB0518.namprd15.prod.outlook.com>",
"subject": "Nested Message With Attachment",
"bodyPreview": "PFAThanks,Adele",
"importance": "normal",
"conversationId": "AAQkADg3NTY5MDg4LWMzYmQtNDQzNi05OTgwLWQyZjg2YWQwMTNkZAAQAO6hkp84oMdGm6ZBsSH72sE=",
"conversationIndex": "AQHW5C+U7qGSnzigx0abpkGxIfvawQ==",
"isDeliveryReceiptRequested": false,
"isReadReceiptRequested": false,
"isRead": true,
"isDraft": false,
"webLink": "https://outlook.office365.com/owa/?ItemID=AAMkADA1M3MTRkOQAAAA%3D%3D&exvsurl=1&viewmodel=ItemAttachment",
"internetMessageHeaders": [],
"body": {
"contentType": "html",
"content": "<html><head>\r\n</head>\r\n<body>\r\n</body>\r\n</html>"
},
"sender": {
"emailAddress": {
"name": "Adele Vance",
"address": "Adele.Vance@microsoft.com"
}
},
"from": {
"emailAddress": {
"name": "Adele Vance",
"address": "Adele.Vance@microsoft.com"
}
},
"toRecipients": [
{
"emailAddress": {
"name": "Adele Vance",
"address": "Adele.Vance@microsoft.com"
}
}
],
"flag": {
"flagStatus": "notFlagged"
},
"attachments": [
{
"@odata.type": "#microsoft.graph.fileAttachment",
"@odata.mediaContentType": "application/pdf",
"id": "AAMkADg3NTYULmbsDYNg==",
"lastModifiedDateTime": "2021-01-21T14:56:18Z",
"name": "Info.pdf",
"contentType": "application/pdf",
"size": 417351,
"isInline": false,
"contentId": null,
"contentLocation": null,
"contentBytes": "JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFuZyhlbi1JTikgL1N0cnVjdFRyZWVSb29"
}
]
}
}
Example 5: Get the properties of a reference attachment
Request
The following example shows a request to get a reference attachment on an event.
GET https://graph.microsoft.com/beta/me/events/AAMkAGE1M88AADUv0uAAAG=/attachments/AAMkAGE1Mg72tgf7hJp0PICVGCc0g=
Response
The following example shows the response. Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users/ddfcd489-628b-40d7-b48b-57002df800e5/events/AAMkAGE1M88AADUv0uAAAG%3D/attachments/$entity",
"@odata.type": "#microsoft.graph.referenceAttachment",
"id": "AAMkAGE1Mg72tgf7hJp0PCGVCIc0g=",
"lastModifiedDateTime": "2016-03-12T06:04:38Z",
"name": "Personal pictures",
"contentType": null,
"size": 382,
"isInline": false,
"sourceUrl": "https://contoso.com/personal/mario_contoso_net/Documents/Pics",
"providerType": "oneDriveConsumer",
"thumbnailUrl": null,
"previewUrl": null,
"permission": "edit",
"isFolder": true
}
Example 6: Get the raw contents of a file attachment on a message
Request
The following example shows a request to get the raw contents of a Word file that has been attached to a message.
GET https://graph.microsoft.com/beta/me/messages/AAMkAGUzY5QKjAAA=/attachments/AAMkAGUzY5QKjAAABEgAQAMkpJI_X-LBFgvrv1PlZYd8=/$value
Response
The following example shows the response. The actual response body includes the raw bytes of the file attachment, which are abbreviated here for brevity.
HTTP/1.1 200 OK
{Raw bytes of the file}
Example 7: Get the MIME raw contents of a contact attachment on a message
Request
The following example shows a request to get the raw contents of a contact item that has been attached to a message.
GET https://graph.microsoft.com/beta/me/messages/AAMkADI5MAAGjk2PxAAA=/attachments/AAMkADI5MAAGjk2PxAAABEgAQACEJqrbJZBNIlr3pGFvd9K8=/$value
Response
The following example shows the response.
HTTP/1.1 200 OK
BEGIN:VCARD
PROFILE:VCARD
VERSION:3.0
MAILER:Microsoft Exchange
PRODID:Microsoft Exchange
FN:Alex Wilbur
N:Wilbur;Alex;;;
NOTE:Sunday\, June 10\, 2012 5:44 PM:\nGutter\, window cleaning\, pressure
washing\, roof debris blowing\n
ORG:Contoso;
CLASS:PUBLIC
ADR;TYPE=WORK,PREF:;;4567 Main St;Buffalo;NY;98052;United States of America
LABEL;TYPE=WORK,PREF:4567 Main St\nBuffalo\, NY 98052
ADR;TYPE=HOME:;;;;;;
ADR;TYPE=POSTAL:;;;;;;
TEL;TYPE=WORK:(425) 555-0100
TITLE:
X-MS-IMADDRESS:
REV;VALUE=DATE-TIME:2019-04-09T02:13:31,161Z
END:VCARD
Example 8: Get the MIME raw contents of an event attachment on a message
Request
The following example shows a request to get the raw contents of an event that has been attached to a message.
GET https://graph.microsoft.com/beta/me/messages/AAMkADVIOAAA=/attachments/AAMkADVIOAAABEgAQACvkutl6c4FMifPyS6NvXsM=/$value
Response
The following example shows the response.
HTTP/1.1 200 OK
BEGIN:VCALENDAR
METHOD:PUBLISH
PRODID:Microsoft Exchange Server 2010
VERSION:2.0
BEGIN:VTIMEZONE
TZID:Pacific Standard Time
BEGIN:STANDARD
DTSTART:16010101T020000
TZOFFSETFROM:-0700
TZOFFSETTO:-0800
RRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=1SU;BYMONTH=11
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:16010101T020000
TZOFFSETFROM:-0800
TZOFFSETTO:-0700
RRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=2SU;BYMONTH=3
END:DAYLIGHT
END:VTIMEZONE
BEGIN:VEVENT
ORGANIZER;CN=Adele Vance:MAILTO:adelev@contoso.com
ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN=Adele Vance:MAILTO:adelev@contoso.com
DESCRIPTION;LANGUAGE=en-US:\n
UID:040000008200
SUMMARY;LANGUAGE=en-US:Review Megan's docs
DTSTART;TZID=Pacific Standard Time:20190409T140000
DTEND;TZID=Pacific Standard Time:20190409T160000
CLASS:PUBLIC
PRIORITY:5
DTSTAMP:20190409T211833Z
TRANSP:OPAQUE
STATUS:CONFIRMED
SEQUENCE:0
LOCATION;LANGUAGE=en-US:
X-MICROSOFT-CDO-APPT-SEQUENCE:0
X-MICROSOFT-CDO-OWNERAPPTID:0
X-MICROSOFT-CDO-BUSYSTATUS:BUSY
X-MICROSOFT-CDO-INTENDEDSTATUS:BUSY
X-MICROSOFT-CDO-ALLDAYEVENT:FALSE
X-MICROSOFT-CDO-IMPORTANCE:1
X-MICROSOFT-CDO-INSTTYPE:0
X-MICROSOFT-DONOTFORWARDMEETING:FALSE
X-MICROSOFT-DISALLOW-COUNTER:FALSE
X-MICROSOFT-LOCATIONS:[]
BEGIN:VALARM
DESCRIPTION:REMINDER
TRIGGER;RELATED=START:-PT15M
ACTION:DISPLAY
END:VALARM
END:VEVENT
END:VCALENDAR
Example 9: Get the MIME raw contents of a meeting invitation item attachment on a message
Request
The following example shows a request to get the raw contents of a meeting invitation (of the eventMessage type) that has been attached to a message. The eventMessage entity is based on the message type.
GET https://graph.microsoft.com/beta/me/messages/AAMkAGUzY5QKiAAA=/attachments/AAMkAGUzY5QKiAAABEgAQAK8ktgiIO19OqkvUZAqLmyQ=/$value
Response
The following example shows the response.
The response body includes the eventMessage attachment in MIME format. The body of the eventMessage is truncated for brevity. The full message body is returned from an actual call.
HTTP/1.1 200 OK
From: Megan Bowen <MeganB@contoso.com>
To: Adele Vance <AdeleV@contoso.com>
Subject: Let's go for lunch
Thread-Topic: Let's go for lunch
Thread-Index: AdTPqxOmg4AXoJV960a1j5NrJCHYjA==
X-MS-Exchange-MessageSentRepresentingType: 1
Date: Thu, 28 Feb 2019 21:17:58 +0000
Message-ID:
<CY4PR2201MB1046E9C83FC42478EF4EE283C9750@CY4PR2201MB1046.namprd22.prod.outlook.com>
Content-Language: en-US
X-MS-Has-Attach:
X-MS-Exchange-Organization-SCL: -1
X-MS-TNEF-Correlator:
X-MS-Exchange-Organization-RecordReviewCfmType: 0
Content-Type: multipart/alternative;
boundary="_000_CY4PR2201MB1046E9C83FC42478EF4EE283C9750CY4PR2201MB1046_"
MIME-Version: 1.0
--_000_CY4PR2201MB1046E9C83FC42478EF4EE283C9750CY4PR2201MB1046_
Content-Type: text/plain; charset="us-ascii"
Does mid month work for you?
--_000_CY4PR2201MB1046E9C83FC42478EF4EE283C9750CY4PR2201MB1046_
Content-Type: text/html; charset="us-ascii"
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
</head>
<body>
Does mid month work for you?
</body>
</html>
--_000_CY4PR2201MB1046E9C83FC42478EF4EE283C9750CY4PR2201MB1046_
Content-Type: text/calendar; charset="utf-8"; method=REQUEST
Content-Transfer-Encoding: base64
QkVHSU46VkNBTEVOREFSDQpNRVRIT0Q6UkVRVUVTVA0KUFJPRElEOk1pY3Jvc29mdCBFeGNoYW5n
--_000_CY4PR2201MB1046E9C83FC42478EF4EE283C9750CY4PR2201MB1046_--