The Email Integration allows you to set up a dedicated email inbox for your AI chatbot, enabling seamless communication between your bot and users via email. This integration is particularly useful for managing customer support queries, automated responses, and asynchronous conversations where users prefer email communication over real-time chat.

When you create an Email Integration, ChatBotKit generates a unique email address (inbox) that routes incoming messages to your configured bot. The bot processes these emails and can respond automatically, maintaining conversation context across multiple email exchanges within the configured session duration.

Creating an Email Integration

To create a new Email Integration, you need to configure several key parameters that control how your bot handles email interactions. The integration requires linking to an existing bot and allows you to customize various behaviors such as contact collection, session management, and attachment handling.

The basic setup requires providing a name and description for identification purposes. You must also link the integration to a bot that will handle the incoming emails. Optionally, you can link to a blueprint for more complex configurations:

POST /api/v1/integration/email/create
Content-Type: application/json

{
  "name": "Support Email Bot",
  "description": "Automated email support for customer inquiries",
  "botId": "bot_abc123",
  "contactCollection": true,
  "sessionDuration": 3600000,
  "attachments": true
}
http

Configuration Parameters

Bot Linking: The botId parameter connects your Email Integration to a specific bot that will process incoming emails. This bot should be configured with appropriate instructions and knowledge to handle email-based conversations.

Contact Collection: When enabled, the integration automatically captures contact information from email senders, including their email addresses and any other details provided in the conversation. This is useful for building contact lists and tracking user interactions.

Session Duration: This parameter (in milliseconds) determines how long the bot maintains conversation context. For example, setting this to 3600000 (1 hour) means the bot will remember previous exchanges within a 1-hour window, enabling more coherent multi-email conversations.

Attachments: Enable this option if you want your bot to receive and process email attachments. The bot can access file information and, depending on its configuration, may be able to analyze document contents.

Blueprint Integration: Linking to a blueprint allows you to use pre-configured setups that include datasets, skillsets, and other resources. This is useful for deploying consistent configurations across multiple integrations.

Generated Inbox Address

After creating the integration, ChatBotKit generates a unique email address that serves as your bot's inbox. This address is typically in the format [unique-identifier]@[domain].chatbotkit.com. All emails sent to this address will be processed by your configured bot.

Share this inbox address with your users or configure it as a forwarding destination from your existing support email systems. The inbox can handle multiple concurrent conversations and will route each sender's emails to separate conversation threads.

Important Considerations

Response Time: Email responses are processed asynchronously. While the bot typically responds within seconds, email delivery times depend on standard email protocols and may take longer during high-volume periods.

Security: The generated inbox address should be treated as a public endpoint. Do not share sensitive authentication tokens or credentials via the inbox address itself. Use the integration's metadata field for secure configuration storage.

Rate Limits: Email integrations are subject to platform rate limits to prevent abuse. High-volume use cases should contact support for appropriate configuration.

For detailed setup instructions and advanced configuration options, refer to the Email Integration guide in the documentation.

Deleting an Email Integration

To permanently remove an Email Integration, use the delete endpoint. This operation is irreversible and will immediately stop the integration from processing new emails. The generated inbox address will become inactive and any emails sent to it after deletion will no longer be processed.

POST /api/v1/integration/email/{emailIntegrationId}/delete
Content-Type: application/json

{}
http

What Gets Deleted

When you delete an Email Integration, the following occurs:

Inbox Deactivation: The unique email address generated for this integration immediately stops accepting new messages. Any emails sent to this address after deletion will bounce or be rejected.

Configuration Removal: All integration settings, including contact collection preferences, session duration configuration, and attachment handling settings, are permanently removed from the system.

Resource Links: The connections between this integration and its associated bot and blueprint are severed. However, the bot and blueprint themselves remain intact and can be used with other integrations or applications.

What Persists After Deletion

Important data is preserved even after integration deletion:

Conversation History: All conversations that occurred through this integration remain available in your conversation logs. You can still access, search, and analyze these historical interactions even though the integration itself is deleted.

Collected Contacts: If contact collection was enabled, the contacts gathered through this integration remain in your contact database. These contacts are not deleted and can continue to be used for analytics or other purposes.

Associated Resources: The bot, blueprint, datasets, and any other resources linked to this integration are not affected by the deletion. Only the integration configuration itself is removed.

Before You Delete

Consider these factors before deleting an Email Integration:

Notification Updates: If you've shared the inbox email address with users, customers, or in documentation, update those references to prevent confusion when emails to the old address start bouncing.

Active Conversations: Any ongoing email conversations will be interrupted. Users who reply to recent emails may not receive responses after the integration is deleted.

Alternative Approaches: If you need to temporarily disable the integration, consider updating its configuration instead of deletion. You can modify the linked bot to provide "out of office" style responses rather than completely removing the integration.

Recovery

Deleted integrations cannot be recovered. You would need to create a new Email Integration, which will receive a new, different inbox address. The original inbox address cannot be reused once an integration is deleted.

Fetching Email Integration Details

Retrieve complete configuration details for a specific Email Integration by its ID. This endpoint returns all settings and resource links associated with the integration, allowing you to inspect current configurations, verify settings, or programmatically manage your email bot infrastructure.

GET /api/v1/integration/email/{emailIntegrationId}/fetch
http

Response Details

The fetch endpoint returns comprehensive information about the Email Integration:

Identification Details: The response includes the unique integration ID, name, and description you assigned during creation. Use these identifiers to reference the integration in your applications or documentation.

Resource Relationships: You'll receive the IDs of linked resources including the associated bot (botId) and blueprint (blueprintId if configured). These IDs allow you to query the linked resources for additional details about how the integration operates.

Configuration Settings: All operational parameters are included in the response:

• contactCollection: Whether the integration captures contact information
• sessionDuration: The conversation context window in milliseconds
• attachments: Whether email attachments are processed

Metadata and Timestamps: The response includes custom metadata stored with the integration, as well as createdAt and updatedAt timestamps that track when the integration was created and last modified.

Use Cases for Fetching Integration Details

Configuration Audits: Regularly fetch integration details to verify that configurations remain correct and haven't been inadvertently modified. This is particularly important in environments where multiple team members manage integrations.

Programmatic Management: When building administrative dashboards or automation tools, use the fetch endpoint to retrieve current settings before making updates. This ensures you preserve configurations you don't intend to change.

Troubleshooting: When investigating issues with email bot responses or behavior, fetch the integration details to verify that all resource links are correct and settings match your expectations.

Documentation and Reporting: Generate reports about your email bot infrastructure by fetching details for multiple integrations. This helps with capacity planning, usage analysis, and compliance documentation.

Integration with Other Operations

The information returned by fetch is often used as input for update operations. For example, you might fetch the current configuration, modify specific fields, and then send the updated configuration to the update endpoint. This pattern ensures you don't accidentally clear or reset fields you didn't intend to change.

Note: The fetch operation is read-only and does not modify the integration in any way. It's safe to call as frequently as needed for monitoring or verification purposes.

Setting Up an Email Integration

The setup endpoint allows you to initialize or reconfigure an Email Integration after creation. This operation prepares the integration for active use by validating configurations, establishing necessary connections, and ensuring all required resources are properly linked and accessible.

While Email Integrations are immediately functional after creation, the setup operation is useful when you need to refresh configurations, verify connectivity, or reinitialize the integration after making changes to linked resources such as bots or blueprints:

POST /api/v1/integration/email/{emailIntegrationId}/setup
Content-Type: application/json

{}
http

When to Use Setup

The setup operation is particularly useful in these scenarios:

After Configuration Changes: If you've updated the associated bot's instructions, modified the blueprint, or changed any resource links, running setup ensures the integration reflects these changes.

Troubleshooting: When experiencing issues with email processing or bot responses, running setup can help identify and resolve configuration problems by revalidating all connections.

Migration or Restoration: After importing integrations from backups or moving configurations between environments, setup ensures everything is properly initialized in the new context.

Setup Process

During setup, the system performs several validation and initialization steps:

• Verifies the linked bot exists and is accessible
• Validates blueprint resources (if configured)
• Confirms the inbox address is properly routed
• Ensures session management is correctly configured
• Validates attachment handling capabilities

The setup operation is idempotent, meaning you can safely run it multiple times without causing issues. Each execution performs the same validation and initialization steps regardless of the integration's current state.

Error Handling

If setup encounters configuration issues, it will return detailed error information indicating what needs to be corrected. Common issues include missing or inaccessible bots, invalid blueprint references, or permission problems. Address these issues and run setup again to complete the process.

Note: The setup operation does not modify your integration's configuration settings. It only validates and initializes the integration based on its current configuration. Use the update endpoint to change configuration parameters.

Listing Email Integrations

Retrieve all Email Integrations associated with your account by sending a GET request to the list endpoint. This is useful for managing multiple email bots, auditing your configurations, or building administrative dashboards that display all active email integrations.

The list endpoint supports pagination and filtering options to help you navigate through large numbers of integrations efficiently. Results are returned with comprehensive details about each integration, including their configuration parameters and linked resources:

GET /api/v1/integration/email/list
http

Pagination and Filtering

When working with multiple Email Integrations, you can use cursor-based pagination to retrieve results in manageable chunks. The cursor parameter allows you to fetch subsequent pages of results:

GET /api/v1/integration/email/list?cursor=CURSOR_VALUE&take=20
http

The take parameter controls how many items are returned per request, while the order parameter (asc or desc) determines the sorting order based on creation date.

Response Structure

Each integration in the response includes complete configuration details:

• Basic Information: ID, name, and description
• Resource Links: Associated bot ID and blueprint ID (if configured)
• Configuration Options: Contact collection, session duration, attachments
• Metadata: Custom metadata, creation date, and last update timestamp

Use this information to identify which integrations need updates, monitor active configurations, or programmatically manage your email bot infrastructure.

Blueprint Filtering

If you organize your integrations using blueprints, you can filter the list to show only integrations associated with a specific blueprint. This is helpful for managing different deployment environments or customer segments:

GET /api/v1/integration/email/list?blueprintId=BLUEPRINT_ID
http

This query returns only the Email Integrations that are linked to the specified blueprint, making it easier to manage grouped configurations.