Skip to content
builders.ac

Mailbox API · Beta

List messages

GET
/azure/v1.0/users/{email}/messages
curl --request GET \
  --url 'https://api.builders.ac/api/mailbox/v1beta1/azure/v1.0/users/sender%40yourdomain.com/messages?%24select=id%2Csubject%2Cfrom%2CreceivedDateTime%2CisRead&%24filter=receivedDateTime%20ge%202026-07-01T00%3A00%3A00Z&%24top=25&%24orderby=receivedDateTime%20desc' \
  --header 'Authorization: Bearer <token>'

Lists messages in the mailbox. Mirrors Graph’s GET /users/{id}/messages.

OData query parameters are forwarded to Microsoft untouched, so $select, $filter, $top, $orderby and $search behave exactly as they do against Graph directly. $search additionally requires the ConsistencyLevel: eventual header, which is one of the headers the proxy forwards.

@odata.nextLink in the response is rewritten to this API, so SDK page iterators work unchanged.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
email
required
string format: email

The mailbox address, which must belong to the account owning the API key. A mailbox that exists but is not yours returns 404 rather than 403, so this endpoint cannot be used to discover which addresses are builders.ac mailboxes.

Example
sender@yourdomain.com

Query Parameters

Section titled “Query Parameters”
$select
string

Comma-separated properties to return. Strongly recommended — the default projection is large.

Example
id,subject,from,receivedDateTime,isRead
$filter
string

OData filter expression.

Example
receivedDateTime ge 2026-07-01T00:00:00Z
$top
integer
>= 1 <= 999

Page size.

Example
25
$orderby
string
Example
receivedDateTime desc

Responses

Section titled “Responses”

200

Section titled “200”

A page of messages.

Media typeapplication/json
object
value
Array<object>

A Graph message. Only commonly used properties are listed; the full Graph resource is returned and accepted.

object
id

Opaque message id. Forward it byte-for-byte — ids contain =, + and /.

string
subject
string
body
object
contentType
string
default: text
Allowed values: text html
content
required
string
bodyPreview
string
from
object
emailAddress
required
object
name
string
address
required
string format: email
toRecipients
Array<object>
object
emailAddress
required
object
name
string
address
required
string format: email
ccRecipients
Array<object>
object
emailAddress
required
object
name
string
address
required
string format: email
receivedDateTime
string format: date-time
sentDateTime
string format: date-time
isRead
boolean
hasAttachments
boolean
conversationId
string
internetMessageId
string
@odata.nextLink

Link to the next page, rewritten to point at this API rather than graph.microsoft.com. Follow it with the same API key.

string format: uri
Example
{
  "value": [
    {
      "body": {
        "contentType": "text"
      },
      "from": {
        "emailAddress": {
          "name": "Jane Doe",
          "address": "jane@example.com"
        }
      },
      "toRecipients": [
        {
          "emailAddress": {
            "name": "Jane Doe",
            "address": "jane@example.com"
          }
        }
      ],
      "ccRecipients": [
        {
          "emailAddress": {
            "name": "Jane Doe",
            "address": "jane@example.com"
          }
        }
      ]
    }
  ]
}

Headers

Section titled “Headers”
x-sending-upstream-id
string

Microsoft’s own request id for the upstream call, re-emitted as x-sending-upstream-id. Quote this when raising an issue with Microsoft support.

400

Section titled “400”

Malformed request — for example an invalid OData query or a body Graph refused.

Media typeapplication/json
OData error

Microsoft’s error shape, used on the /azure surface so Graph SDKs deserialise failures as ordinary errors.

object
error
required
object
code
required

Microsoft’s error code for the status.

string
Allowed values: BadRequest InvalidAuthenticationToken ErrorAccessDenied ResourceNotFound RequestNotSupported RequestEntityTooLarge TooManyRequests UnknownError NotImplemented ServiceUnavailable Timeout
message
required
string
innerError
object
request-id

Correlation id for this request. Quote it in support requests.

string
date
string format: date-time
Example
{
  "error": {
    "code": "BadRequest",
    "message": "The request is malformed or incorrect.",
    "innerError": {
      "request-id": "a26397a7-04e1-4c8f",
      "date": "2026-07-31T08:24:57+00:00"
    }
  }
}

401

Section titled “401”

Missing or invalid API key. Also returned when the key has been revoked.

Media typeapplication/json
OData error

Microsoft’s error shape, used on the /azure surface so Graph SDKs deserialise failures as ordinary errors.

object
error
required
object
code
required

Microsoft’s error code for the status.

string
Allowed values: BadRequest InvalidAuthenticationToken ErrorAccessDenied ResourceNotFound RequestNotSupported RequestEntityTooLarge TooManyRequests UnknownError NotImplemented ServiceUnavailable Timeout
message
required
string
innerError
object
request-id

Correlation id for this request. Quote it in support requests.

string
date
string format: date-time
Example
{
  "error": {
    "code": "InvalidAuthenticationToken",
    "message": "The API key is invalid or has been revoked.",
    "innerError": {
      "request-id": "a26397a7-04e1-4c8f",
      "date": "2026-07-31T08:24:57+00:00"
    }
  }
}

403

Section titled “403”

The credential is valid, but its Core customer account is inactive.

Media typeapplication/json
OData error

Microsoft’s error shape, used on the /azure surface so Graph SDKs deserialise failures as ordinary errors.

object
error
required
object
code
required

Microsoft’s error code for the status.

string
Allowed values: BadRequest InvalidAuthenticationToken ErrorAccessDenied ResourceNotFound RequestNotSupported RequestEntityTooLarge TooManyRequests UnknownError NotImplemented ServiceUnavailable Timeout
message
required
string
innerError
object
request-id

Correlation id for this request. Quote it in support requests.

string
date
string format: date-time
Example
{
  "error": {
    "code": "ErrorAccessDenied",
    "message": "This account is inactive.",
    "innerError": {
      "request-id": "a26397a7-04e1-4c8f",
      "date": "2026-07-31T08:24:57+00:00"
    }
  }
}

404

Section titled “404”

Either the mailbox is not yours (or does not exist), or the Graph path is outside the allow-list. Both answer 404 so the API does not disclose which.

Media typeapplication/json
OData error

Microsoft’s error shape, used on the /azure surface so Graph SDKs deserialise failures as ordinary errors.

object
error
required
object
code
required

Microsoft’s error code for the status.

string
Allowed values: BadRequest InvalidAuthenticationToken ErrorAccessDenied ResourceNotFound RequestNotSupported RequestEntityTooLarge TooManyRequests UnknownError NotImplemented ServiceUnavailable Timeout
message
required
string
innerError
object
request-id

Correlation id for this request. Quote it in support requests.

string
date
string format: date-time
Example
{
  "error": {
    "code": "ResourceNotFound",
    "message": "No such mailbox.",
    "innerError": {
      "request-id": "a26397a7-04e1-4c8f",
      "date": "2026-07-31T08:24:57+00:00"
    }
  }
}

429

Section titled “429”

Rate limit exceeded — 60 requests per minute per credential and per account.

Media typeapplication/json
OData error

Microsoft’s error shape, used on the /azure surface so Graph SDKs deserialise failures as ordinary errors.

object
error
required
object
code
required

Microsoft’s error code for the status.

string
Allowed values: BadRequest InvalidAuthenticationToken ErrorAccessDenied ResourceNotFound RequestNotSupported RequestEntityTooLarge TooManyRequests UnknownError NotImplemented ServiceUnavailable Timeout
message
required
string
innerError
object
request-id

Correlation id for this request. Quote it in support requests.

string
date
string format: date-time
Example
{
  "error": {
    "code": "TooManyRequests",
    "message": "Too many requests. Retry after the number of seconds in Retry-After.",
    "innerError": {
      "request-id": "a26397a7-04e1-4c8f",
      "date": "2026-07-31T08:24:57+00:00"
    }
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.

X-RateLimit-Limit
integer
X-RateLimit-Remaining
integer
X-RateLimit-Reset
integer

Unix timestamp at which the window resets.

502

Section titled “502”

Microsoft Graph could not be reached, or its response was too large to relay.

For sendMail this is ambiguous: the message may already have been accepted and sent. Do not retry automatically.

Media typeapplication/json
OData error

Microsoft’s error shape, used on the /azure surface so Graph SDKs deserialise failures as ordinary errors.

object
error
required
object
code
required

Microsoft’s error code for the status.

string
Allowed values: BadRequest InvalidAuthenticationToken ErrorAccessDenied ResourceNotFound RequestNotSupported RequestEntityTooLarge TooManyRequests UnknownError NotImplemented ServiceUnavailable Timeout
message
required
string
innerError
object
request-id

Correlation id for this request. Quote it in support requests.

string
date
string format: date-time
Example
{
  "error": {
    "code": "UnknownError",
    "message": "Could not reach Microsoft Graph. The request may not have been processed; retry only if it is safe to repeat.",
    "innerError": {
      "request-id": "a26397a7-04e1-4c8f",
      "date": "2026-07-31T08:24:57+00:00"
    }
  }
}

503

Section titled “503”

The Mailbox API is temporarily unavailable, or credentials could not be verified. Safe to retry with backoff.

Media typeapplication/json
OData error

Microsoft’s error shape, used on the /azure surface so Graph SDKs deserialise failures as ordinary errors.

object
error
required
object
code
required

Microsoft’s error code for the status.

string
Allowed values: BadRequest InvalidAuthenticationToken ErrorAccessDenied ResourceNotFound RequestNotSupported RequestEntityTooLarge TooManyRequests UnknownError NotImplemented ServiceUnavailable Timeout
message
required
string
innerError
object
request-id

Correlation id for this request. Quote it in support requests.

string
date
string format: date-time
Example
{
  "error": {
    "code": "BadRequest"
  }
}