Mailbox API · Beta

Send mail

POST

/azure/v1.0/users/{email}/sendMail

const url = 'https://api.builders.ac/api/mailbox/v1beta1/azure/v1.0/users/sender%40yourdomain.com/sendMail';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"message":{"subject":"Following up","body":{"contentType":"html","content":"<p>Hi — following up on my last note.</p>"},"toRecipients":[{"emailAddress":{"address":"prospect@example.com"}}]},"saveToSentItems":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.builders.ac/api/mailbox/v1beta1/azure/v1.0/users/sender%40yourdomain.com/sendMail \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "message": { "subject": "Following up", "body": { "contentType": "html", "content": "<p>Hi — following up on my last note.</p>" }, "toRecipients": [ { "emailAddress": { "address": "prospect@example.com" } } ] }, "saveToSentItems": true }'

Sends a message as the mailbox in the path. Mirrors Graph’s POST /users/{id}/sendMail.

Returns 202 Accepted with an empty body once Microsoft has accepted the message — that is acceptance for delivery, not proof of delivery.

This operation is not retried for you. If the forward to Graph fails at the transport layer, the request may still have been accepted and sent upstream, so the proxy surfaces 502 rather than risking a duplicate send. Treat a 502 here as unknown, not failed, and only retry if sending twice is acceptable.

Bodies larger than 10 MB are rejected with 413 before any call to Microsoft. Graph itself rejects payloads over roughly 4 MB, so attachments should stay well below that.

Authorizations

BearerAuth

Parameters

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

Request Body^required

application/json

Graph’s sendMail payload, passed through unchanged.

object

message

required

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

object

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

saveToSentItems

Whether to keep a copy in Sent Items.

boolean

default: true

Responses

202

Accepted by Microsoft for delivery. Empty body.

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

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

application/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

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

application/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

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

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

application/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

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

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.

application/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

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"
    }
  }
}

413

Request body above 10 MB. Rejected before any call to Microsoft.

application/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

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"
  }
}

429

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

application/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

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

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

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.

application/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

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

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

application/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

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"
  }
}

Send mail

Authorizations

Parameters

Path Parameters

Example

Request Bodyrequired

Responses

202

Headers

400

Example

401

Example

403

Example

404

Example

413

Example

429

Example

Headers

502

Example

503

Example

Request Body^required