Skip to main content
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

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.
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 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 Sendmux 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 SENDMUX_API_KEY environment variable:

​
Response fields

The response uses the standard { ok, data, meta } envelope. 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

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 Sendmux 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.
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 Sendmux 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.
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.
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.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

API keys

Create and manage scoped credentials.

Postman collections

Try the connection request in the matching API collection.