> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an integration and manage its inboxes

> Validate a Qubrics connection, select an authorised inbox and manage its lifecycle.

Use a connection endpoint to check a credential before running a workflow. The response identifies the team and credential, lists its permissions, and provides a connection label.

## Choose the endpoint

| API | Connection test | Credential requirement |
| - | - | - |
| Sending | `GET https://smtp.qubrics.com/api/v1/me` | A Sending credential or REST OAuth grant with `email.send`. |
| Management | `GET https://app.qubrics.com/api/v1/me` | A root or integration API key, or REST OAuth grant with Management access; no additional read permission. |
| Mailbox | `GET https://app.qubrics.com/api/v1/mailbox/connection` | A mailbox or integration credential, or supported access token with Mailbox access; no additional read permission. |

Use the same credential for the connection test and the workflow. A send-only key does not need a Management key to connect. Root API keys are rejected by the Mailbox connection endpoint; mailbox keys are rejected by the Management connection endpoint.

These checks do not send email, check credits or provider readiness, read mailbox storage, or require a mailbox selection. A successful connection test confirms authentication for that API. Each workflow action still enforces its permissions and service requirements.

> [!NOTE]
>
> `GET /mailbox/me` remains available for mailbox details and storage usage. Use
> `GET /mailbox/connection` when testing authentication.

For user-approved access, complete [OAuth authorisation](https://sendmux.ai/docs/developer-tools/oauth.md) and use the resulting access token in the same connection test.

## Configure the connection test

**1. Store the credential**

Create a key with the permissions your workflow needs under **API Keys** in
the Qubrics app. Save it in your integration platform's credential store.

**2. Make an authenticated GET request**

Select the endpoint above and send `Authorization: Bearer` followed by the
credential. The request needs no body or query parameters.

**3. Read the result**

Accept an HTTP `200` response with `ok: true`. Use `data.label` as the display
label, `data.team.id` as the stable account identifier, and
`data.credential.id` when you need to distinguish credentials for the same team.

For example, with a Sending key stored in the `QUBRICS_API_KEY` environment variable:

```bash theme={null}
curl --fail-with-body https://smtp.qubrics.com/api/v1/me \
  --header "Authorization: Bearer $QUBRICS_API_KEY"
```

## Response fields

The response uses the standard `{ ok, data, meta }` envelope.

| Field | Meaning |
| - | - |
| `data.team.id` | Stable public identifier of the authenticated team. |
| `data.team.name` | Current team name. |
| `data.credential.id` | Public identifier of this API key, agent token, or connected-app grant. |
| `data.credential.type` | `api_key`, `agent_token`, or `oauth`. |
| `data.credential.name` | Key or application name; `null` when no name applies. |
| `data.label` | Team name and credential name when available. Names may change; do not use the label as an identifier. |
| `data.permissions` | Permissions available to this credential. Actions may require additional permissions. |
| `data.mailboxes` | Authorised mailbox identifiers and email addresses, when applicable. An empty array does not mean the team has no mailboxes. |
| `meta.request_id` | Request identifier to include when contacting support. |

The response does not expose the key creator's profile, a credential secret, or a mailbox password. A credential identifies access to a team or mailbox; it does not necessarily identify a human user.

## Handle connection failures

| HTTP status | Handling |
| - | - |
| `401` | Authentication failed. Ask the user to reconnect or replace the credential. |
| `403` | The credential cannot access this API, or lacks its required permission. Check the endpoint and credential scope. |
| `429` | Wait at least the `Retry-After` interval before trying again. |
| `503` | Authentication is temporarily unavailable. Keep the connection and retry after `Retry-After`. |

Do not shorten the server's retry interval or disconnect a saved credential because of a temporary `429` or `503` response. If your workflow cannot wait that long, report the delay and retry later.

Authenticated responses include `Cache-Control: no-store`. Authentication is checked again on conditional requests using `If-None-Match`; a matching representation returns a bodyless `304`. Omit this header for a connector's initial connection test so it receives the response fields.

## Automation platforms

For viaSocket, Zapier, Make, n8n, or Activepieces, configure the platform's API-key connection test with the same GET request and response-field mapping above. This is also suitable for a custom HTTP workflow.

Keep connection validation separate from sending a test email. Use credentials scoped to the actions your integration exposes. Platform-specific OAuth, trigger, and publishing requirements are separate from this API-key connection check.

## Manage native inboxes with an integration credential

An integration credential has access to all current and future inboxes in its Qubrics team, subject to its permissions and sending restrictions. Use a dedicated team for an integration that should own only its native inboxes. Ordinary root keys, single-mailbox keys and connected-app grants keep their existing scopes.

> [!NOTE]
>
> This procedure requires an explicitly issued **Mailbox Integration** credential. A successful connection test does not issue one or widen an existing credential's access.

**1. Confirm the team and workspace owner**

Validate the integration credential with a connection endpoint and record `data.team.id`. Before creating, accessing or retiring a native inbox, confirm that the requesting workspace owns that inbox in your integration's records. Team-wide Qubrics access does not enforce your integration's workspace boundaries.

**2. Create an inbox and retain its ID**

Use `POST /mailboxes` with `mailbox.admin.create`. Supply an `email` on a verified domain available to the team, and retain the returned `data.mailbox.id` and `data.mailbox.email`. Reuse the same `Idempotency-Key` and request body if the response is lost.

```bash theme={null}
curl -X POST https://app.qubrics.com/api/v1/mailboxes \
  -H "Authorization: Bearer $QUBRICS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: native-inbox-create-1" \
  -d '{"email":"agent@example.com","display_name":"Agent"}'
```

Integration provisioning does not return a separate mailbox credential. Use the integration credential to access the new inbox. Creating the inbox does not grant extra sender addresses beyond the applicable sending policies.

**3. Select the inbox on Mailbox API requests**

Use `GET /mailboxes` with `mailbox.admin.read` to list the team's inboxes. Pass exactly one `mailbox_id` on Mailbox API operations, even when the team has only one inbox. The connection test itself needs no mailbox selection.

```bash theme={null}
curl --get https://app.qubrics.com/api/v1/mailbox/messages \
  -H "Authorization: Bearer $QUBRICS_API_KEY" \
  --data-urlencode "mailbox_id=$MAILBOX_ID" \
  --data-urlencode "limit=10"
```

Set `MAILBOX_ID` to the retained inbox public ID. Missing selection returns `400`; an unknown, foreign or inactive inbox returns `404`. Reading requires `mailbox.read`; saving drafts also requires `mailbox.drafts.write`, and sending or scheduling also requires `email.send`.

**4. Retire the owned inbox and reconcile costs**

Stop new work for the inbox in your integration, then call `DELETE /mailboxes/{public_id}` with `mailbox.admin.delete`. Confirm the response has `data.deleted: true` and the expected `data.id`. Keep the inbox ID and original team identity for [cost reconciliation](https://sendmux.ai/docs/developer-tools/mailbox-costs.md).

If deletion returns `503`, wait for the `Retry-After` interval before retrying the same inbox deletion. A `404` alone does not confirm deletion.

A successful deletion does not make pending costs final. Read the retained cumulative cost window until its overall state is `final`. Keep pending readings open, and never replace a failed read with zero. Revoking the integration credential stops access to every inbox it covers; it is not a substitute for retiring one inbox.

Monid-native workflows use newly provisioned inboxes in the dedicated team. Linking an existing account is outside this workflow. Monid connection onboarding, native credits and final usage settlement are separate integration requirements.

## Next steps

> [card] [API keys](https://sendmux.ai/docs/account/api-keys.md)
>
> Create and manage scoped credentials.

> [card] [Postman collections](https://sendmux.ai/docs/developer-tools/postman.md)
>
> Try the connection request in the matching API collection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.