Overview

A drop-in Microsoft Graph proxy for mailboxes you provisioned through builders.ac.

builders.ac Mailbox API v1beta1

The Mailbox API lets you send and read mail from mailboxes you own on builders.ac using an unmodified Microsoft Graph SDK. Point your Graph client at this base URL and we exchange your builders.ac credential for the mailbox tenant’s Microsoft Graph token.

Stability

v1beta1 is a beta contract. The legacy v1alpha1 path remains operational during migration, but new integrations should use this version and the unified Core credential below.

Authentication

Send the public age1… API credential as a bearer token:

Authorization: Bearer age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The matching age identity (the API secret) stays on your machine. Do not send it in the Authorization header or any Mailbox API request. It is used only when registering the credential and when opening sealed values for APIs that explicitly require that proof. The same active Core credential can authenticate the Mailbox, Deliverability, and Provisioning API surfaces.

Using a Microsoft Graph SDK

The /azure surface mirrors Graph’s URL layout, so an official SDK works unchanged. Keep Microsoft’s nested API version at v1.0:

import { Client } from '@microsoft/microsoft-graph-client';

const apiKey = process.env.SENDING_AC_API_KEY; // age1… public credential
const client = Client.init({
  baseUrl: 'https://api.builders.ac/api/mailbox/v1beta1/azure',
  defaultVersion: 'v1.0',
  authProvider: (done) => done(null, apiKey),
  customHosts: new Set(['api.builders.ac']),
});

await client.api('/users/sender@yourdomain.com/sendMail').post({ message, saveToSentItems: true });

The SDK only attaches Authorization to trusted hosts and refuses plain HTTP, so customHosts and TLS are required.

Paging and errors

@odata.nextLink, related OData links, and rewritten message links point back to v1beta1; SDK page iterators never leave the proxy. Errors on /azure use Microsoft’s OData error shape so Graph SDKs deserialize them as ordinary GraphErrors. Errors on /events and /problems use RFC 9457 problem details whose type URLs also remain on v1beta1.

Rate limits and retries

The Graph surface and /events share a 60-request-per-minute budget, enforced per credential and per account. Exceeding it returns 429 with Retry-After and rate-limit headers. sendMail is never retried after an ambiguous transport failure because Microsoft may already have accepted it; retry only if a duplicate send is acceptable. Read-only calls are safe to retry.

Events

GET /events lists messages observed on your mailboxes over the last seven days, including direction and best-effort classification. Only mailboxes with a live Microsoft Graph subscription are observed. Classification typically appears within about two minutes but delayed mailbox mapping can take longer. Poll with an overlap and deduplicate on id so late-classified messages are not missed.

builders.ac support

• https://api.builders.ac

Information

• OpenAPI version: 3.1.0

Operations

GET

/

GET

/problems

GET

/problems/{code}

POST

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

GET

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

GET

/azure/v1.0/users/{email}/messages/{id}

GET

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

GET

/events

POST

/events/subscriptions

GET

/google/v1/{path}

Authentication

BearerAuth

An active Core age1… API credential generated in the builders.ac customer portal. Send only this public credential. Its matching age identity (API secret) stays on the caller’s machine and is never sent with a Mailbox API request.

Security scheme type: http

Bearer format: age1…