Unified Provider API: Simplifying Email Integration

We’re excited to announce Sunnybox API v1.6.0, a major update that consolidates and simplifies how you work with email providers. This release represents a significant architectural improvement that makes integrating multiple email providers easier than ever.

What’s New?

Unified Provider Endpoint

Previously, managing email providers required navigating different endpoints for different provider types. With v1.6.0, all provider operations are now consolidated under a single, intuitive endpoint:

/api/v1/providers

This means whether you’re working with IMAP, Gmail, or future provider types, you’ll use the same consistent API surface.

Gmail OAuth2 Support

We’re introducing support for Gmail providers using OAuth2 authentication. While full automated OAuth flow is coming soon (pending CASA verification), you can already integrate Gmail accounts by providing your own OAuth tokens:

{
  "provider": {
    "providerType": "gmail",
    "email": "[email protected]",
    "accessToken": "ya29.a0AfH6SMBx...",
    "refreshToken": "1//0gYv8n7..."
  }
}

Simplified Configuration Model

We’ve eliminated the complexity of polymorphic relationships. Instead of tracking providableType and providableId, provider configurations are now embedded directly within the provider object:

Before (v1.5.0 and earlier):

{
  "name": "[email protected]",
  "providableType": "ImapProvider",
  "providableId": 123
}

Now (v1.6.0):

{
  "name": "[email protected]",
  "providerType": "imap",
  "config": {
    "type": "imap",
    "email": "[email protected]",
    "host": "imap.example.com",
    "port": 993,
    // ... other IMAP-specific settings
  }
}

Enhanced Security with New ID Format

Provider IDs now use a URL-safe Base58 format (e.g., h8Kzj9Tx5mFqL3Nw7pRcVb2Y) instead of sequential integers. This improves security by making IDs non-guessable while maintaining compatibility with URL routing.

Improved Autoconfig

Creating IMAP providers is now even easier with enhanced autoconfig detection. For most popular email providers, you only need to provide an email and password:

{
  "provider": {
    "providerType": "imap",
    "email": "[email protected]",
    "password": "your-password"
  }
}

The API automatically detects the correct IMAP and SMTP settings for providers like Gmail, Outlook, Yahoo, and many others.

Migration Guide

Updating Your Integration

1. API Endpoints: Replace calls to /api/v1/imap_providers with /api/v1/providers

2. Request Format: Update your provider creation requests to use the new unified format:

   {
     "provider": {
       "providerType": "imap",
       "email": "[email protected]",
       "password": "password"
       // Optional: specify manual configuration
     }
   }
   

3. Response Handling: Provider configurations are now nested under the config field in responses

4. ID Format: Update any ID validation to accept the new Base58 string format

Breaking Changes

This is a breaking change. The old /api/v1/imap_providers endpoints have been removed completely. You must update your integration to use the new unified /api/v1/providers endpoint.

We understand breaking changes can be disruptive, but this consolidation significantly improves the API’s consistency and maintainability. The migration is straightforward, and the new structure sets us up for better extensibility going forward.

What’s Coming Next?

• Automated Gmail OAuth Flow: Once our CASA verification is complete, you’ll be able to authenticate Gmail accounts directly through Sunnybox without managing OAuth tokens yourself
• Additional Provider Types: The new architecture makes it easy for us to add support for more email providers
• Enhanced Provider Management: Bulk operations, provider templates, and more

Get Started

Check out our updated API documentation to explore the new unified provider API. The improved OpenAPI specification includes comprehensive examples for all provider types.

We’re confident this consolidation will make your email integration experience smoother and more maintainable. As always, we’d love to hear your feedback!

Happy coding!