Email Integration

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:

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]@integration.chatbotkit.email. 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.

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.

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:

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.

Updating an Email Integration

Modify the configuration of an existing Email Integration to adjust bot behavior, session management, feature enablement, or resource linkage. Updates take effect immediately for new incoming emails while preserving the integration's unique inbox address and maintaining existing conversation history and contact records.

Updating email integrations is essential for evolving your email automation strategy. Common update scenarios include switching to an improved bot version, enabling contact collection for lead generation, adjusting session duration for better conversation continuity, enabling attachment processing, or linking to updated blueprints with enhanced datasets and skillsets.

Configuration Parameter Details

Bot Replacement: Changing the botId redirects all future email conversations to a different bot. This is particularly useful when deploying improved bot versions with better response quality, updated knowledge bases, or specialized handling capabilities. Historical conversations remain accessible under the original bot but new emails will be processed by the updated bot configuration.

Contact Collection: Enabling contactCollection instructs the integration to automatically capture and store contact information from email senders. The system extracts email addresses, names when available, and associates them with conversation history. This builds a valuable contact database for marketing, support follow-ups, and relationship management. Disabling this feature maintains privacy but foregoes contact tracking benefits.

Session Duration Management: The sessionDuration parameter (measured in milliseconds) determines how long the bot remembers context between emails from the same sender. Longer durations enable multi-email conversations where the bot recalls previous exchanges, creating more natural, contextual interactions. For example, setting 7200000 (2 hours) means emails within a 2-hour window share conversation context. Shorter durations treat each email more independently, suitable for one-off inquiries.

Attachment Processing: Enabling attachments allows your bot to receive, access, and process email attachments. The bot can analyze document contents, extract information from files, or provide context-aware responses based on attachment data. This is valuable for support scenarios involving screenshots, documents, or data files. Disable this if attachments aren't needed to improve processing speed and reduce resource usage.

Blueprint Switching: Updating blueprintId applies a different set of pre-configured resources to your email integration. Blueprints bundle datasets, skillsets, abilities, and configuration into reusable templates. Switching blueprints enables rapid deployment of enhanced capabilities or standardized configurations across multiple email integrations simultaneously.

Update Strategy Recommendations

Incremental Changes: When making significant configuration changes, consider updating one parameter at a time to isolate any unexpected behavior and simplify troubleshooting. Test each change with sample emails before proceeding to the next update.

Notification Management: If your email integration sends automated responses, inform your users or team when significant changes are deployed, especially when switching bots or modifying response behavior patterns.

Testing Protocol: After updates, send test emails covering various scenarios to verify the integration behaves as expected. Pay special attention to context retention when modifying session duration and attachment handling when enabling that feature.

Monitoring Conversations: Review the Conversations tab after deploying updates to ensure emails are being processed correctly and responses meet quality expectations. Look for any errors or unexpected behavior patterns that might indicate configuration issues.

Important Note: The integration's unique inbox email address never changes, regardless of configuration updates. This ensures external systems and users can continue sending emails to the same address without disruption, even as the underlying bot and behavior evolve.

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:

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:

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:

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