Table of contents

• Getting Started
  • Providers
  • API Keys
  • Streams for Webhooks
  • Dashboard
• Accessing the API
  • Using Restish CLI
    • Setup
    • Usage
• API Structure
  • Health
  • Providers
  • Messages
  • Threads
  • Streams
  • Jobs

Getting Started #

Sunnybox has three main components you can make use of to get started. There are Providers, API Keys and Streams. You also have access to the Dashboard showing you your usage stats.

Providers #

Message providers form the core infrastructure of your hub, facilitating the retrieval and transmission of messages on your behalf.

To initiate the process, integrate a provider. You have the flexibility to integrate multiple providers as per your requirements. Sunnybox supports multiple provider types including IMAP (standard email servers) and Gmail (OAuth2 authentication).

API Keys #

Message providers form the core infrastructure of your hub, facilitating the retrieval and transmission of messages on your behalf.

Copy your API Key and use it in your applications to access your messages. You can also use it to access your messages directly our OpenAPI docs. In the OpenAPI docs click on Authorize and paste your API Key in the field. You can also create more API keys for different applications and restrict access specifying READ, WRITE and DELETE permissions.

Streams for Webhooks #

Streams are used for Webhooks. You can group Message Providers to Streams and assign a Webhook URL.

Whenever a new message arrives it gets forwarded to the specified Webhook URL. The URL has to be HTTPS. You can optionally provide Basic Auth credentials.

Dashboard #

The Dashboard gives you a quick usage overview showing you your total API Calls, Active Providers, API keys and Streams. More analytics will be added later on.

Accessing the API #

After you have set up and enabled your first provider, it is available via our API. In this section you learn how to access the API via our Swagger documentation and via your own Apps. Visit our OpenAPI docs and click on authorize. Then paste in an API Key you created in the API Keys section of the admin panel. Now your requests are authenticated and you can access your resources via our API. Every endpoint is documented and you can find the input and outputs as well as an example response in the OpenAPI documentation together with an example of how to access using curl. Because Sunnybox adheres to the OpenAPI specification you can simply generate the client for you favorite programming language using the official OpenAPI Generator.

Using Restish CLI #

Restish is a powerful CLI tool for interacting with REST APIs. It provides an intuitive way to access the Sunnybox API directly from your terminal.

Setup #

1. Install Restish following their installation guide
2. Configure Sunnybox as an API:

   restish api configure sunnybox https://api.sunnybox.io
   

3. Edit the default profile to add authentication:
   • When prompted, select “Edit Default Profile”
   • Set Headers:
     • Name: Authorization
     • Value: Bearer YOUR_API_KEY
   • Save & Exit

Usage #

Once configured, you can easily access Sunnybox via CLI:

restish sunnybox [command]

For example:

• restish sunnybox health - Check API health
• restish sunnybox providers-list - List all providers
• restish sunnybox messages-list provider_xyz_id - List messages from a specific provider

Watch this quick setup video to see it in action:

API Structure #

The API is structured into five main categories: Health, Providers, Messages, Threads and Streams.

Health #

This is the endpoint you should call to check if the API is available.

Providers #

Under this unified endpoint you can manage all your email providers. You can create, read, update and delete providers of any type (IMAP, Gmail, etc.).

The provider configuration is embedded directly within the provider object, making it easy to manage different provider types through a single, consistent API interface. You can enable or disable providers using the PATCH method with the active field.

Messages #

Under this endpoint you can manage your messages. Here you can read, send and delete messages. Further you can extract attachments from messages.

Threads #

The threads endpoint lets you page through email threads showing the whole message tree of messages and replies.

Streams #

Configure webhooks for real-time message notifications by grouping providers into streams with callback URLs.

Jobs #

Monitor background operations like email sending with detailed status updates.