The Outlook mail API in Microsoft Graph provides methods that support sending messages.
Send message
There are two ways to send a message using Graph API.
One way is to create a draft of a new message.
POST https://graph.microsoft.com/v1.0/me/messages
{
"subject":"Message",
"importance":"Normal",
"body":{
"contentType":"HTML",
"content":"Normal message"
},
"toRecipients":[
{
"emailAddress":{
"address":"john.doe@contoso.com"
}
}
]
}
and then send a previously created message draft.
POST https://graph.microsoft.com/v1.0/me/messages/{message_id}/send
Alternatively, you can send a new message in one step.
POST https://graph.microsoft.com/v1.0/me/sendMail
{
"message": {
"subject": "Message",
"body": {
"contentType": "HTML",
"content": "Normal message"
},
"toRecipients": [
{
"emailAddress": {
"address": "john.doe@contoso.com"
}
}
]
}
}
Delay delivery
What if you have a use case that requires sending a message at a specific date and time or with a delay?
The message resource type doesn't expose any properties to defer sending a message.
Set deferred send time
Fortunately, the Graph API provides the extended properties REST API if you need to access custom data for Outlook MAPI properties that are not already exposed in the Microsoft Graph API.
Outlook MAPI provides the canonical property PidTagDeferredSendTime.
PidTagDeferredSendTime indicates a time when a client would like to defer sending a message.
| Property | Value |
|---|---|
| Associated properties | PR_DEFERRED_SEND_TIME |
| Identifier | 0x3FEF |
| Data type | PT_SYSTIME |
Draft message
When creating a draft of a message, provide a JSON body of the singleValueLegacyExtendedProperty object in the singleValueExtendedProperties collection property of the message resource instance.
singleValueLegacyExtendedProperty has properties id and value.
id must follow the format "{graph_type} {proptag}".
graph_type for MAPI data type PT_SYSTIME is SystemTime, and proptag is 0x03FEF.
The date and time value must be in ISO 8601 format.
POST https://graph.microsoft.com/v1.0/me/messages
{
"subject": "Delayed message",
"importance": "Normal",
"body": {
"contentType": "HTML",
"content": "This is a <b>delayed</b> message."
},
"toRecipients": [
{
"emailAddress": {
"address": "john.doe@contoso.com"
}
}
],
"singleValueExtendedProperties": [
{
"id": "SystemTime 0x3FEF",
"value": "2023-05-31T09:05:00Z"
}
]
}
The response body contains a message object with the id of the message.
{
...
"id": "AA...AjYy1cIAAA=",
...
}
Use the id of the draft message to send the draft.
POST https://graph.microsoft.com/v1.0/me/messages/{message_id}/send
The message will be stored in Drafts folder until the deferred send time is reached.
Send mail
When using the /me/sendMail endpoint to send a message in one step, the request is similar.
POST https://graph.microsoft.com/v1.0/me/sendMail
{
"message": {
"subject": "Delayed message",
"body": {
"contentType": "HTML",
"content": "This is a <b>delayed</b> message."
},
"toRecipients": [
{
"emailAddress": {
"address": "john.doe@contoso.com"
}
}
],
"singleValueExtendedProperties": [
{
"id": "SystemTime 0x3FEF",
"value": "2023-05-31T09:05:00Z"
}
]
}
}
Compute deferred send time
The value of the PidTagDeferredSendTime can be computed from PidTagDeferredSendUnits and PidTagDeferredSendNumber by using the following formula:
PidTagDeferredSendTime = PidTagClientSubmitTime + PidTagDeferredSendNumber * TimeOf(PidTagDeferredSendUnit)
PidTagClientSubmitTime is set when the Graph API sends a draft (me/messages/{message_id}/send) or a message (/me/sendMail).
PidTagDeferredSendUnits specifies the unit of time by which the PidTagDeferredSendNumber property value should be multiplied.
The possible values are: 0 (minutes), 1 (hours), 2 (days), and 3 (weeks).
| Property | Value |
|---|---|
| Associated properties | PR_DEFERRED_SEND_UNITS |
| Identifier | 0x3FEC |
| Data type | PT_LONG |
PidTagDeferredSendNumber contains a number from range 0-999 that can be used to compute the deferment of sending a message.
| Property | Value |
|---|---|
| Associated properties | PR_DEFERRED_SEND_NUMBER |
| Identifier | 0x3FEB |
| Data type | PT_LONG |
Example: Send message in 5 minutes
To delay a message for 5 minutes set PidTagDeferredSendNumber = 5 and PidTagDeferredSendUnits = 0:
POST https://graph.microsoft.com/v1.0/me/sendMail
{
"message": {
"subject": "Delayed message",
"body": {
"contentType": "HTML",
"content": "This is a <b>delayed</b> message."
},
"toRecipients": [
{
"emailAddress": {
"address": "john.doe@contoso.com"
}
}
],
"singleValueExtendedProperties": [
{
"id": "Integer 0x3FEB",
"value": "5"
},
{
"id": "Integer 0x3FEC",
"value": "0"
}
]
}
}
Similar for a draft message:
POST https://graph.microsoft.com/v1.0/me/messages
{
"subject": "Delayed message",
"importance": "Normal",
"body": {
"contentType": "HTML",
"content": "This is a <b>delayed</b> message."
},
"toRecipients": [
{
"emailAddress": {
"address": "john.doe@contoso.com"
}
}
],
"singleValueExtendedProperties": [
{
"id": "Integer 0x3FEB",
"value": "5"
},
{
"id": "Integer 0x3FEC",
"value": "0"
}
]
}
Use the id from the response to send the draft:
POST https://graph.microsoft.com/v1.0/me/messages/{message_id}/send
The countdown for delayed delivery begins after the draft is sent.
