Integrations

Create an integration

Create an integration for the current environment the user is based on the API key provided. Each provider supports different credentials, check the provider documentation for more details. Only integration metadata is returned, credentials field is returned as an empty object.

post/v1/integrations

Request body

namestring

The name of the integration

identifierstring

The unique identifier for the integration

_environmentIdstring uuid

The ID of the associated environment

providerIdstring

The provider ID for the integration

The channel type for the integration. Not required for agent-kind integrations.

kind'delivery' | 'agent'

Distinguishes delivery integrations from agent-runtime integrations. Defaults to "delivery". Agent integrations do not require a channel.

activeboolean

If the integration is active, the validation on the credentials field will run

checkboolean

Flag to check the integration status

rulesobject nullable

JSONLogic used at send time to select this integration. Takes precedence over conditions.

configurationsobject

Configurations for the integration

Example request

{
  "rules": {
    "==": [
      {
        "var": "context.tenant.id"
      },
      "acme"
    ]
  }
}

Response

Created

_idstring

The unique identifier of the integration record in the database. This is automatically generated.

_environmentIdstring required

The unique identifier for the environment associated with this integration. This links to the Environment collection.

_organizationIdstring required

The unique identifier for the organization that owns this integration. This links to the Organization collection.

namestring required

The name of the integration, which is used to identify it in the user interface.

identifierstring required

A unique string identifier for the integration, often used for API calls or internal references.

providerIdstring required

The identifier for the provider of the integration (e.g., "mailgun", "twilio").

The channel type for the integration, which defines how it communicates (e.g., email, SMS). Not set for agent-kind integrations.

kind'delivery' | 'agent'

Distinguishes delivery integrations from agent-runtime integrations. Defaults to "delivery". Agent integrations do not have a channel.

activeboolean required

Indicates whether the integration is currently active. An active integration will process events and messages.

deletedboolean required

Indicates whether the integration has been marked as deleted (soft delete).

deletedAtstring

The timestamp indicating when the integration was deleted. This is set when the integration is soft deleted.

deletedBystring

The identifier of the user who performed the deletion of this integration. Useful for audit trails.

primaryboolean required

Indicates whether this integration is marked as primary. A primary integration is often the default choice for processing.

rulesobject nullable

JSONLogic used at send time to select this integration. Takes precedence over conditions.

Example response

{
  "rules": {
    "==": [
      {
        "var": "context.tenant.id"
      },
      "acme"
    ]
  }
}

Changes

Changed in 5 of the 13 revisions of this API.112

Sep 3, 2026268501525ad84See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  request property deprecated
  request-property-deprecated
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  response property conditions deprecated
  response-property-deprecated
Aug 28, 20262dc8476c472f2See the full diff
- ○
  added the new optional request property /////
  new-optional-request-property
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
Aug 16, 2026d7137c47680a2See the full diff
- ○
  added the new optional request property /////
  new-optional-request-property
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
Jul 31, 202647f16ff4d4271See the full diff
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 21, 20262e115ea8160c13See the full diff
- ●
  added the new tool enum value to the response property for the response status
  response-property-enum-value-added
- ○
  added the new optional request property /////
  new-optional-request-property
- ○
  added the new tool enum value to the request property
  request-property-enum-value-added
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added

Full history