Quick Start Guide

Get up and running with Inbox in under 5 minutes. Send your first message and set up webhooks.

What You'll Build

In this guide, you'll learn how to:

Send your first message

Create an account and send an OTP message

Set up webhooks

Receive delivery and read confirmations

Handle rich messages

Send interactive messages with buttons

Test your integration

Verify everything works end-to-end

Create Your Account

Create Free Account

Get Your API Key

After signing up, you'll find your API key in the dashboard:

API Key: sk_live_1234567890abcdef...

Keep your API key secure and never expose it in client-side code.

Send Your First Message

Let's send a simple OTP message using cURL:

cURL Example

curl -X POST https://api.getinbox.app/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "type": "otp",
    "body": {
      "code": "123456",
      "purpose": "signin",
      "expires_at": "2025-01-15T10:30:00Z"
    }
  }'

Node.js

const response = await fetch(
  'https://api.getinbox.app/v1/send',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+15551234567',
      type: 'otp',
      body: {
        code: '123456',
        purpose: 'signin',
        expires_at: new Date(
          Date.now() + 10 * 60 * 1000
        ).toISOString()
      }
    })
  }
);

const result = await response.json();
console.log('Message sent:', result.id);

Python

import requests
from datetime import datetime, timedelta

response = requests.post(
    'https://api.getinbox.app/v1/send',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'to': '+15551234567',
        'type': 'otp',
        'body': {
            'code': '123456',
            'purpose': 'signin',
            'expires_at': (
                datetime.now() + timedelta(minutes=10)
            ).isoformat() + 'Z'
        }
    }
)

result = response.json()
print(f"Message sent: {result['id']}")

Set Up Webhooks

Webhooks notify your application when messages are delivered, read, or when users interact with them.

Create a Webhook Endpoint

// Express.js webhook handler
app.post('/webhooks/inbox', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-inbox-signature'];
  const payload = req.body;
  
  // Verify signature (important for security)
  if (!verifySignature(payload, signature, process.env.INBOX_WEBHOOK_SECRET)) {
    return res.status(401).send('Unauthorized');
  }
  
  const event = JSON.parse(payload);
  
  switch (event.type) {
    case 'message.delivered':
      console.log('Message delivered:', event.data.message_id);
      break;
    case 'message.read':
      console.log('Message read:', event.data.message_id);
      break;
    case 'message.action':
      console.log('Button clicked:', event.data.action);
      break;
  }
  
  res.status(200).send('OK');
});

Register Your Webhook

curl -X POST https://api.getinbox.app/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/inbox",
    "events": ["message.delivered", "message.read", "message.action"],
    "description": "Production webhook endpoint"
  }'

Send Rich Messages

Now let's send a more complex message with interactive buttons:

Interactive Message

{
  "to": "+15551234567",
  "type": "custom",
  "body": {
    "title": "Order Confirmation",
    "content": "Your order #A-123 has been confirmed and will be delivered tomorrow between 2-6 PM.",
    "actions": [
      {
        "label": "Track Order",
        "url": "https://mystore.com/track/A-123",
        "type": "url"
      },
      {
        "label": "Change Delivery Time",
        "action": "change_delivery",
        "type": "callback"
      }
    ],
    "media": {
      "type": "image",
      "url": "https://mystore.com/images/order-confirmation.jpg",
      "alt": "Order confirmation"
    }
  }
}

Pro Tip: When users tap the "Change Delivery Time" button, you'll receive a webhook with event.type = "message.action" and event.data.action = "change_delivery".

Test Your Integration

Check Message Status

curl -X GET https://api.getinbox.app/v1/messages/msg_1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

This returns the message status, delivery time, and read receipt information.

Test Webhook Delivery

curl -X POST https://api.getinbox.app/v1/webhooks/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_id": "wh_1234567890",
    "event_type": "message.delivered"
  }'

This sends a test webhook to verify your endpoint is working correctly.

Next Steps

API Reference

Complete documentation for all API endpoints and parameters.

Read the docs

Message Schemas

Detailed schemas for OTP, delivery, transaction, and event messages.

View schemas

Webhooks Guide

Learn about webhook events, security, and best practices.

Learn more

Dashboard

Monitor your messages, view analytics, and manage settings.

Open dashboard

Need Help?

Our developer community and support team are here to help you succeed.

Join Discord Community Contact Support