Skip to main content

How to connect a Custom API with Snoooz

With the Custom API integration, Snoooz can call a secure endpoint you provide at reply-time, receive JSON context, and use that context to generate more accurate, personalized email responses.

Written by Victoria

Overview

The Custom API integration lets Snoooz enrich AI replies with data from systems that are not directly built into Snoooz.

For example, when a customer emails your connected inbox, Snoooz can send details from that email to your API, such as the sender’s email address and the message content. Your API can then return structured data about that customer, account, order, subscription, ticket, invoice, or any other record.

Snoooz uses that returned data as context when creating the AI draft or response.

This makes it possible to connect Snoooz to almost any system that can expose a secure REST API.

What you can connect

The Custom API integration can be used with many types of systems, including:

  • Supabase

  • Postgres-backed apps

  • Internal CRMs

  • Customer portals

  • Subscription databases

  • Billing systems

  • Order management systems

  • Helpdesk or ticketing systems

  • Product usage databases

  • Membership platforms

  • Internal admin tools

  • Custom SaaS applications

  • Data warehouses or reporting APIs

  • Any backend that can expose a secure HTTPS endpoint

For Supabase or Postgres, we recommend exposing a controlled API endpoint, such as a Supabase Edge Function, instead of giving Snoooz direct database access. This gives your team control over exactly what data Snoooz can see.

What this integration can help with

The Custom API integration is useful when your team wants Snoooz to answer emails using business-specific data.

For example, Snoooz can help draft replies to questions like:

  • “What is the status of my account?”

  • “Can you check my subscription?”

  • “Has my invoice been paid?”

  • “What plan am I on?”

  • “Can you check my latest order?”

  • “Do I have any open support tickets?”

  • “Can you confirm my usage or account limits?”

  • “What is the status of my onboarding?”

  • “Can you check whether this customer is active?”

  • “Can you look up this member’s details?”

The exact data depends on what your API returns to Snoooz.

How it works

When Snoooz processes an incoming email, it can call your configured API endpoint.

The flow looks like this:

  1. A customer sends an email to your connected inbox.

  2. Snoooz evaluates your rules and determines that AI context should be used.

  3. Snoooz sends a request to your Custom API endpoint.

  4. Your API looks up the relevant data in your system.

  5. Your API returns structured JSON to Snoooz.

  6. Snoooz passes that context to the AI reply engine.

  7. Snoooz drafts or sends a reply based on your Snoooz rules and settings.

For example:

Incoming email → Snoooz calls your API → Your API returns customer/account/order data → Snoooz uses that data to draft a better reply

What Snoooz sends to your API

Snoooz sends a POST request to your configured endpoint.

The request may include details such as:

{
    "provider": "snoooz",
"version": "2026-06",
"companyId": "company_123",
"workspaceId": "workspace_123",
"senderEmail": "[email protected]",
"emailText": "Hi, can you check my latest invoice?",
"lookup": {
"type": "email",
"value": "[email protected]"
    },
"schema": {
"request": {
"method": "POST",
"lookup": {
"type": "email",
"field": "senderEmail"
            }
        }
    }
}

The most important value is usually senderEmail, because many systems use the sender’s email address to find a matching customer, user, member, or account.

What your API should return

Your API should return JSON.

Snoooz expects a small wrapper around the data so it knows whether useful context was found and what should be passed to the AI.

Recommended response format:

{
    "found": true,
"summary": "Alex is on the Pro plan. Account is active. Latest invoice INV-1001 is paid.",
"context": {
"customer": {
"name": "Alex Smith",
"email": "[email protected]",
"plan": "Pro",
"status": "active"
        },
"latestInvoice": {
"invoiceNumber": "INV-1001",
"status": "paid",
"amount": "$99"
        }
    },
"customerId": "cus_123",
"deepLink": "https://app.example.com/customers/cus_123"
}

Required fields

At minimum, your API should return:

{
    "summary": "Short human-readable summary",
    "context": {}
}

Recommended fields

We recommend returning:

{
"found": true,
"summary": "Short human-readable summary",
"context": {},
"customerId": "optional",
"deepLink": "optional"
}

Can I return custom data?

Yes.

Your API can return any structured data you want inside the context object.

For example:

{
    "found": true,
"summary": "Customer is on the Enterprise plan, has 3 open tickets, and is near their seat limit.",
"context": {
"account": {
"plan": "Enterprise",
"status": "active",
"renewalDate": "2026-07-12",
"healthScore": 82
        },
"usage": {
"seatsUsed": 48,
"seatsLimit": 50
        },
"tickets": [
            {
"id": "T-1001",
"status": "open",
"priority": "high",
"subject": "Billing issue"
            },
            {
"id": "T-1002",
"status": "open",
"priority": "normal",
"subject": "Feature question"
            }
        ]
    },
"customerId": "acct_123",
"deepLink": "https://app.example.com/accounts/acct_123"
}

Snoooz does not require your data to be ecommerce-related. You can return account data, billing data, subscription data, product usage data, ticket data, order data, membership data, or any other structured information.

The top-level response wrapper should stay consistent, but the data inside context is flexible.

How Snoooz uses the returned context

Snoooz uses the returned data as context for the AI reply.

For example, if your API returns:

{
    "summary": "Alex is on the Pro plan. Latest invoice INV-1001 is paid.",
"context": {
"customer": {
"name": "Alex",
"plan": "Pro"
        },
"latestInvoice": {
"status": "paid"
        }
    }
}

Snoooz can use that information to draft a reply such as:

Hi Alex,  

I checked your account and can confirm that you are currently on the Pro plan. Your latest invoice, INV-1001, is marked as paid.

The AI response still follows your Snoooz rules, templates, tone settings, and automation settings.

Example: connecting Supabase

You can use Supabase with Snoooz by creating a Supabase Edge Function that acts as your Custom API endpoint.

The recommended setup is:

Snoooz → calls your Supabase Edge Function → the function queries your Supabase/Postgres database → the function returns JSON context to Snoooz

This avoids giving Snoooz direct database access. Your team controls the query, the response format, and which fields are exposed.

Example Supabase table

You might have a table like:

create table customers (   id uuid primary key default gen_random_uuid(),   email text unique not null,   name text,   plan text,   status text,   latest_order text,   tracking_number text );

Example Supabase response

Your Edge Function could return:

{
    "found": true,
"summary": "Alex Test is on the Pro plan. Account status is active. Latest order is ORD-9001, tracking number TRACK123456.",
"context": {
"customer": {
"name": "Alex Test",
"email": "[email protected]",
"plan": "Pro",
"status": "active"
        },
"latestOrder": {
"orderNumber": "ORD-9001",
"trackingNumber": "TRACK123456"
        }
    },
"customerId": "customer_123",
"deepLink": "https://app.example.com/customers/customer_123"
}

Snoooz can then use this context when replying to the customer’s email.

Authentication

Your Custom API endpoint should be secured.

Snoooz can connect using authentication methods such as:

  • No authentication, for testing only

  • Bearer token

  • API key header

  • Basic authentication

For production use, we recommend using a Bearer token or API key header.

Example:

Authorization: Bearer your-secret-token

Your API should verify the token before returning data.

How to connect a Custom API in Snoooz

Once the Custom API integration has been enabled for your workspace:

  1. Open Snoooz.

  2. Go to Integrations.

  3. Open the Global Integrations section.

  4. Find Custom API.

  5. Click Connect.

  6. Enter your HTTPS endpoint URL.

  7. Choose the authentication method.

  8. Enter the required token, API key, or credentials.

  9. Click Connect.

Snoooz will test the endpoint before saving the integration.

Endpoint requirements

Your endpoint must:

  • Be a public HTTPS URL

  • Accept POST requests

  • Return valid JSON

  • Respond within the configured timeout

  • Return context in the expected response wrapper

  • Be able to authenticate Snoooz requests if authentication is enabled

For testing, you can use tools like Webhook.site, Pipedream, or a temporary test endpoint. For real data, we recommend using a controlled backend endpoint or serverless function.

Example request and response

Request from Snoooz

{
    "provider": "snoooz",
"version": "2026-06",
"companyId": "company_123",
"workspaceId": "workspace_123",
"senderEmail": "[email protected]",
"emailText": "Hi, can you check my order?",
"lookup": {
"type": "email",
"value": "[email protected]"
    }
}

Response from your API

{
    "found": true,
"summary": "Alex has one recent order, ORD-9001, which has shipped with UPS. Tracking number is TRACK123456.",
"context": {
"customer": {
"name": "Alex",
"email": "[email protected]"
        },
"latestOrder": {
"orderNumber": "ORD-9001",
"status": "shipped",
"carrier": "UPS",
"trackingNumber": "TRACK123456"
        }
    },
"customerId": "cus_123",
"deepLink": "https://app.example.com/customers/cus_123"
}

What Snoooz does not do

The Custom API integration is designed to enrich email replies with context.

By default, Snoooz does not:

  • Modify records in your system

  • Create users

  • Delete users

  • Issue refunds

  • Change subscription plans

  • Update invoices

  • Change order status

  • Write data back to your database

  • Run arbitrary database queries

Snoooz uses the information returned by your API to help draft or send better email replies based on your rules and settings.

Troubleshooting

Custom API does not appear in my integrations page

The integration may not be enabled for your workspace. Contact [email protected] and ask to try the Custom API integration.

My connection failed

Check that:

  • Your endpoint is a valid public HTTPS URL

  • Your endpoint accepts POST requests

  • Your endpoint returns valid JSON

  • Your authentication settings are correct

  • Your endpoint responds within the timeout

  • Your endpoint returns the expected response wrapper

Snoooz is not receiving useful context

Check that your API response includes a useful summary and context.

For best results, include a short summary that explains the most important facts Snoooz should use in the reply.

Snoooz is not finding a customer or account

Make sure your API is using the sender email address from the Snoooz request.

For example, if the email sender is:

[email protected]

your API should use that value to look up the matching customer, user, member, or account.

Supabase function returns 401

If you are using a Supabase Edge Function, make sure the function allows external requests and that your own Bearer token check is configured correctly.

For public webhook-style functions, you may need to disable Supabase’s built-in JWT verification and handle authentication inside your function.

Need help?

The Custom API integration is currently available by request.

To enable it or test it with your Snoooz workspace, contact us at:

[email protected]

Related Articles
How the Rules Work in Snoooz?
How to Use AI Replies in Snoooz?
Connect Snoooz to Claude via MCP
Connect Snoooz to ChatGPT via MCP
How to connect BigCommerce with Snoooz
Did this answer your question?