This tutorial will guide you through the process of connecting a user’s email account to Convore. We will show you how to do it via our Dashboard and via our API.

Quick Start - Use Convore’s identity

If you’re just getting started or in the development phase, the easiest way to connect a user’s email account is by using Convore’s built-in identity. This method is perfect for testing and getting a feel for how Convore works. Let’s dive into the steps:

Authorize via Dashboard

  1. Start by logging into your Convore dashboard. Once you’re in, click on the Channels tab.
  2. Here, you’ll see an Add New button. Click on it to start the process of adding a new channel.
  3. A dropdown menu will appear. Select the Provider option from this menu.
  4. You’ll now be presented with a list of email providers. Choose Gmail or Outlook, depending on the user’s email provider.
  5. After selecting the provider, click on the Create button. This action will redirect you to the login page of the selected email provider.
  6. Now, you’ll need to enter the user’s email credentials and grant the necessary permissions for Convore to access the email account.
  7. Once the authorization is successful, you’ll be redirected back to the Convore dashboard. You’ll notice that the new channel is now listed under the Channels tab. The Channel ID for the account you just connected will be displayed on the dashboard. Make sure to copy this ID and keep it safe. You’ll need this ID for API calls to specify which user account’s data Convore should access.

And that’s it! You’ve successfully connected a user’s email account using the Convore dashboard. This method is straightforward and perfect for getting started quickly. In the next section, we’ll cover how to authorize a user’s email account via the API.

Authorize via API

If you’re looking to integrate Convore’s functionality directly into your application, you can use the API to authorize a user’s email account. This method provides a seamless user experience as everything happens within your application. Here’s how you can do it:

  1. The first step is to initiate the authorization process. You do this by making a POST request to the /authorization_flows endpoint. In this request, you need to specify the connector_id parameter as convore_gmail or convore_outlook, depending on the email provider. Also, don’t forget to provide the redirect URIs. Here’s an example of how to do it:
curl --request POST \
  --url https://api.convore.dev/v1/authorization_flows \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "connector_id": "convore_gmail",
  "error_redirect_uri": "https://www.yourapp.com/error",
  "success_redirect_uri": "https://www.yourapp.com/success"
}'
  1. Once you’ve made the request, the API will respond with a URL. This URL is crucial as it’s where the user will authorize Convore to access their email account. So, the next step is to redirect the user to this URL.
{
  // ...
  "grant_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.readonly&state=...",
}
  1. After the user is redirected, they’ll be asked to log in to their email account and grant the necessary permissions for Convore to access it. Once they’ve done that, they’ll be redirected back to your application using the redirect URI you specified in the first step.

  2. Now that the user’s email account is connected, you’ll want to retrieve the Channel ID for this new connection. You can do this by making a GET request to the /channels endpoint. This will return a list of all channels, including the one you just created. Here’s how you can do it:

curl --request GET \
  --url https://api.convore.dev/v1/channels \
  --header 'Authorization: Bearer <token>'

Look for the new channel in the response and note down its ID. You’ll need this Channel ID for future API calls to specify which user account’s data Convore should access.

And there you have it! You’ve successfully connected a user’s email account using the Convore API. This method is a bit more technical than using the dashboard, but it offers a more integrated user experience. Plus, it gives you more control over the process, which can be beneficial as you scale your application.

Go Live - Use your own identity

When you’re ready to move your application from the development phase to production, it’s recommended to set up your own connector using your own Gmail (GCP) or Outlook (Azure) app credentials. This is because, during the Quick Start phase, you’re using Convore’s built-in identity, which is shared among all users in the development environment.

However, in a live environment, you’ll want to have more control over the access and permissions granted to your application. By setting up your own connector, you can manage these aspects more effectively. Additionally, using your own credentials ensures that your application’s email interactions are tied to your own identity, providing a more consistent and professional experience for your end-users.

Set up a Connector via Dashboard

  1. Navigate to the Convore dashboard and select the Connectors tab.
  2. Click on the Add New button.
  3. Choose the Provider option from the dropdown menu.
  4. Select the Gmail option.
  5. Enter your application’s client_id and client_secret obtained from the email provider’s developer console. These credentials are unique to your application and will be used to authenticate your application with the email provider.
  6. Click on the Create button. The new connector will now be listed under the Connectors tab.

Create Connectors via API

If you prefer to automate the process or need to create multiple connectors, you can use the Convore API to create connectors. This method provides more flexibility and can be integrated into your application’s setup process. Here’s how you can do it:

  1. Make a POST request to the /connectors endpoint. In this request, you need to provide the client_id and client_secret that you obtained from your email provider’s developer console. You also need to specify the provider and give a name to your connector. Here’s an example of how to do it:
curl --request POST \
  --url https://api.convore.dev/v1/connectors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "gmail": {
    "client_id": "1234567890-abcdefg.apps.googleusercontent.com",
    "client_secret": "ABCDefGHIJKLMNOpQRStuv"
  },
  "name": "Acme Corps Gmail OAuth App",
  "provider": "gmail",
}'

In this example, replace <token> with your Convore API token, "1234567890-abcdefg.apps.googleusercontent.com" with your actual client_id, and "ABCDefGHIJKLMNOpQRStuv" with your actual client_secret.

  1. Once you’ve made the request, the API will respond with the details of the newly created connector, including its ID. Make sure to save this ID as you’ll need it for future API calls.
{
  "id": "conntr_01hcf9x766fqk8g7hz74363j9q",
  "provider": "gmail",
  "name": "Acme Corps Gmail OAuth App",
  "gmail": {
    "client_id": "1234567890-abcdefg.apps.googleusercontent.com"
  },
  "created_at": "2023-11-07T05:31:56Z",
}

By following these steps, you can successfully create a connector using the Convore API. This method is a bit more technical than using the dashboard, but it offers more flexibility and can be easily integrated into your application’s setup process.

Authorize

The authorization process for using your own identity is similar to the steps mentioned above in the Quick Start section. The main difference is that you’ll be using your own connector instead of Convore’s built-in identity.

  1. Initiate the authorization process by making a POST request to the /authorization_flows endpoint. In this request, specify the connector_id parameter as the ID of the connector you just created. Also, provide the redirect URIs.
  2. The API will respond with a URL. Redirect the user to this URL to authorize your application to access their email account.
  3. After the user has granted the necessary permissions, they will be redirected back to your application.

By following these steps, you can successfully connect a user’s email account to Convore using your own identity, giving you more control over the email interactions in your application.