Sending integrations

Overview

The sending-integration API exposes TenantCore-defined operations for provider accounts already linked to your TenantCore account. The authorization chain remains: API key → TenantCore account UUID → TenantCore-owned integration/mailbox → provider action The public API never accepts an arbitrary Microsoft tenant, arbitrary external mailbox, or raw provider mailbox identifier as authority to perform work. Current public providers:

Instantly
PlusVibe
Smartlead
ManyReach

ReachKit and Email Bison are not exposed through /v1 until their vendor-supported onboarding/OAuth access is available to TenantCore.

Provider credentials are submitted only when creating a TenantCore integration. TenantCore encrypts and stores them server-side. They are never returned by /v1 list/detail endpoints.

Create an integration

POST /v1/integrations

{
  "provider": "instantly",
  "name": "Primary Instantly Workspace",
  "api_key": "provider-api-key"
}

PlusVibe may also require a workspace_id:

{
  "provider": "plusvibe",
  "name": "Client Workspace",
  "api_key": "provider-api-key",
  "workspace_id": "workspace-id"
}

Example:

curl -X POST https://api.tenantcore.io/v1/integrations \
  -H "Authorization: Bearer $TENANTCORE_API_KEY" \
  -H "Idempotency-Key: integration-create-001" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "instantly",
    "name": "Primary Instantly Workspace",
    "api_key": "provider-api-key"
  }'

TenantCore tests the provider credentials before saving the integration. A successful response contains only safe integration metadata:

{
  "id": "integration-uuid",
  "provider": "instantly",
  "name": "Primary Instantly Workspace",
  "provider_workspace_id": "workspace-id",
  "provider_workspace_name": null,
  "status": "connected",
  "last_tested_at": "2026-09-27T23:00:00+00:00",
  "has_error": false,
  "created_at": "2026-09-27T23:00:00+00:00",
  "updated_at": "2026-09-27T23:00:00+00:00",
  "capabilities": {
    "microsoft_oauth": true,
    "mailbox_refresh": true,
    "mailbox_disconnect": true
  }
}

The provider API key is never echoed back.

PlusVibe workspace selection

If a PlusVibe key can access more than one workspace and no workspace_id is supplied, TenantCore returns 400 plusvibe_workspace_required with a safe list of workspace IDs/names. Resubmit the create request with the selected workspace_id and a new idempotency key.

List integrations

GET /v1/integrations

This returns only integrations owned by the authenticated TenantCore account.

Get one integration

GET /v1/integrations/{integration_id}

The detail response includes a persisted mailbox-connection summary without calling the sending provider:

{
  "id": "integration-uuid",
  "provider": "instantly",
  "name": "Primary Instantly Workspace",
  "status": "connected",
  "has_error": false,
  "mailbox_connections": {
    "total": 12,
    "connected": 10,
    "pending": 1,
    "failed": 1,
    "disconnected": 0,
    "other": 0,
    "has_errors": true
  }
}

This summary is database-backed and stays in the normal read-rate bucket. Use the provider refresh endpoint only when you intentionally want TenantCore to reconcile against the upstream provider. A guessed integration UUID owned by another TenantCore account returns the same 404 integration_not_found shape as a nonexistent UUID.

Test provider connectivity

POST /v1/integrations/{integration_id}/test

curl -X POST \
  https://api.tenantcore.io/v1/integrations/$INTEGRATION_ID/test \
  -H "Authorization: Bearer $TENANTCORE_API_KEY" \
  -H "Idempotency-Key: integration-test-001"

This performs a real provider connectivity check and therefore uses the provider-heavy rate-limit bucket.

List eligible TenantCore mailboxes

GET /v1/integrations/{integration_id}/mailboxes

The list is generated from the authenticated TenantCore account. It contains only TenantCore-provisioned mailboxes from owned BYOT or TenantCore-managed tenants. Example mailbox state:

{
  "mailbox_id": "mailbox-uuid",
  "tenant_id": "microsoft-tenant-guid",
  "tenant_name": "Acme",
  "domain_name": "mail.acme.com",
  "display_name": "Taylor",
  "primary_smtp": "taylor@mail.acme.com",
  "account_enabled": true,
  "managed_by_tenantcore": true,
  "connection": {
    "id": "connection-uuid",
    "status": "connected",
    "provider_account_id": "provider-account-id",
    "provider_account_email": "taylor@mail.acme.com",
    "has_error": false,
    "connected_at": "2026-09-27T23:10:00+00:00",
    "updated_at": "2026-09-27T23:10:00+00:00"
  }
}

Raw provider errors are not returned in the mailbox list.

Start Microsoft authorization for a mailbox

Use the TenantCore mailbox UUID returned from the mailbox API/integration mailbox list:

POST /v1/integrations/{integration_id}/mailboxes/{mailbox_id}/oauth/microsoft/init

Example:

curl -X POST \
  https://api.tenantcore.io/v1/integrations/$INTEGRATION_ID/mailboxes/$MAILBOX_ID/oauth/microsoft/init \
  -H "Authorization: Bearer $TENANTCORE_API_KEY" \
  -H "Idempotency-Key: mailbox-oauth-start-001"

TenantCore validates both resources before contacting the provider:

integration_id must belong to the authenticated TenantCore account.
mailbox_id must be a TenantCore mailbox UUID.
The mailbox’s parent tenant must be owned by the same account.
The mailbox must have been provisioned by TenantCore.
A mailbox already connected/pending on another sending platform is rejected.

Example response:

{
  "status": "pending",
  "integration_id": "integration-uuid",
  "provider": "instantly",
  "mailbox_id": "mailbox-uuid",
  "mailbox": "taylor@mail.acme.com",
  "session_id": "opaque-provider-session",
  "auth_url": "https://...",
  "expires_at": "2026-09-27T23:30:00+00:00"
}

Open auth_url in an interactive browser/popup. Do not attempt to parse or synthesize the URL/state yourself.

Check Microsoft authorization status

GET /v1/integrations/{integration_id}/mailboxes/{mailbox_id}/oauth/microsoft/status?session_id=...

Possible stable states:

pending
connected
failed
expired

When connected, the response can include the provider account ID/name and connection timestamp.

This status check can require an upstream provider request and uses TenantCore’s provider-heavy rate-limit bucket. Do not poll in a tight loop. Respect X-RateLimit-* and Retry-After headers.

If a session becomes failed or expired, start a new authorization session with a new Idempotency-Key.

Reconcile provider state

POST /v1/integrations/{integration_id}/mailboxes/refresh

Refresh is intended for recovery/reconciliation, for example when an OAuth popup was closed after the provider completed the connection. It scans only TenantCore-owned, TenantCore-provisioned mailboxes and reconciles provider state back into TenantCore. Example response:

{
  "integration_id": "integration-uuid",
  "provider": "instantly",
  "checked": 4,
  "connected": 10,
  "newly_connected": 1,
  "unchanged": 3,
  "error_count": 0,
  "status": "success"
}

Provider-specific raw errors are intentionally not returned in this aggregate endpoint.

Disconnect a mailbox

DELETE /v1/integrations/{integration_id}/mailboxes/{mailbox_id}

curl -X DELETE \
  https://api.tenantcore.io/v1/integrations/$INTEGRATION_ID/mailboxes/$MAILBOX_ID \
  -H "Authorization: Bearer $TENANTCORE_API_KEY" \
  -H "Idempotency-Key: mailbox-disconnect-001"

TenantCore verifies integration ownership and mailbox ownership before asking the provider to remove/disconnect the mailbox.

Delete an integration

DELETE /v1/integrations/{integration_id}

Deleting the TenantCore integration removes its stored provider credential record. It does not authorize access to any other provider account or TenantCore account.

One sending platform per mailbox

TenantCore enforces one active/pending sending-platform connection per mailbox. If a mailbox is already connected or connecting through another integration, a new connection attempt returns 409 mailbox_already_connected_elsewhere. Disconnect/switch the existing connection first.

Rate limiting and idempotency

Provider-backed integration writes are classified as Microsoft/provider-heavy operations. The current default is 12 operations per 10 minutes per TenantCore account, with a separate concurrency ceiling. Every integration POST or DELETE request requires Idempotency-Key. OAuth status reads are also provider-heavy because checking status may call the provider. Ordinary list/detail reads remain in the normal read bucket.

Security boundaries

The public sending-integration API does not expose:

raw provider API passthrough
encrypted provider credentials
stored provider API keys
mailbox passwords
TOTP/OATH seeds or current MFA codes
arbitrary external mailbox connection by email address
arbitrary Microsoft tenant connection by tenant GUID
managed-tenant provisioning or CSP operations

Mailbox passwords needed internally by a future provider flow remain server-side in TenantCore’s credential-vault architecture and are never returned through this API.

Overview

Authentication

Endpoints

Sending integrations

Overview

Create an integration

PlusVibe workspace selection

List integrations

Get one integration

Test provider connectivity

List eligible TenantCore mailboxes

Start Microsoft authorization for a mailbox

Check Microsoft authorization status

Reconcile provider state

Disconnect a mailbox

Delete an integration

One sending platform per mailbox

Rate limiting and idempotency

Security boundaries

​Overview

​Create an integration

​PlusVibe workspace selection

​List integrations

​Get one integration

​Test provider connectivity

​List eligible TenantCore mailboxes

​Start Microsoft authorization for a mailbox

​Check Microsoft authorization status

​Reconcile provider state

​Disconnect a mailbox

​Delete an integration

​One sending platform per mailbox

​Rate limiting and idempotency

​Security boundaries

Overview

Create an integration

PlusVibe workspace selection

List integrations

Get one integration

Test provider connectivity

List eligible TenantCore mailboxes

Start Microsoft authorization for a mailbox

Check Microsoft authorization status

Reconcile provider state

Disconnect a mailbox

Delete an integration

One sending platform per mailbox

Rate limiting and idempotency

Security boundaries