API Reference

Complete reference for all YeboLink API endpoints. This page provides a comprehensive overview of available endpoints, grouped by functionality.

Base URL

Production: https://api.yebolink.com
Development: https://dev-api.yebolink.com

Authentication Methods

YeboLink supports two authentication methods:

• API Keys: For sending messages and accessing message data programmatically

  • Header: X-API-Key: ybk_...
  • Use for: Message sending, message retrieval

• JWT Tokens: For dashboard access and account management

  • Header: Authorization: Bearer <token>
  • Use for: Account management, API key creation, billing, webhooks

Endpoints Overview

Authentication

Method	Endpoint	Description	Auth Required
POST	/api/v1/auth/signup	Create new workspace account	None
POST	/api/v1/auth/login	Login to workspace	None
POST	/api/v1/auth/verify-email	Verify email address	None
POST	/api/v1/auth/forgot-password	Request password reset	None
POST	/api/v1/auth/reset-password	Reset password	None

Messages

Method	Endpoint	Description	Auth Required
POST	/api/v1/messages/send	Send a single message	API Key
POST	/api/v1/messages/bulk	Send bulk messages	API Key
GET	/api/v1/messages	Get message history	API Key
GET	/api/v1/messages/:id	Get message by ID	API Key
POST	/api/v1/messages/:id/cancel	Cancel a scheduled message	API Key

Both send endpoints accept an optional scheduled_at field to defer delivery — see Scheduling Messages — and an optional Idempotency-Key header to make retries safe — see Idempotency.

POST /api/v1/messages/send and /api/v1/messages/bulk both take a content object whose fields depend on channel. For channel: "email", this includes content.subject, content.html/content.text, and an optional content.reply_to — the email address recipient replies are routed to (defaults to your workspace's account email if omitted, since every email sends from the shared platform address). See Send Email Messages for the full field reference.

API Keys

Method	Endpoint	Description	Auth Required
POST	/api/v1/api-keys	Create new API key	JWT
GET	/api/v1/api-keys	List all API keys	JWT
DELETE	/api/v1/api-keys/:id	Deactivate API key	JWT

Contacts

Method	Endpoint	Description	Auth Required
POST	/api/v1/contacts	Create new contact	JWT
GET	/api/v1/contacts	List all contacts	JWT
GET	/api/v1/contacts/:id	Get contact by ID	JWT
PUT	/api/v1/contacts/:id	Update contact	JWT
DELETE	/api/v1/contacts/:id	Delete contact	JWT

Inbox

Two-way messaging: inbound replies from customers, threaded into conversations you can read and reply to. See Two-Way Inbox for the full reference, including scopes and the read/unread semantics.

Method	Endpoint	Description	Auth Required
GET	/api/v1/inbox/conversations	List conversations	API Key (read_messages) or JWT
GET	/api/v1/inbox/conversations/:id/messages	Get a conversation's messages	API Key (read_messages) or JWT
POST	/api/v1/inbox/conversations/:id/reply	Reply within a conversation	API Key (send_messages) or JWT
POST	/api/v1/inbox/conversations/:id/read	Mark a conversation read	API Key (read_messages) or JWT
PATCH	/api/v1/inbox/conversations/:id	Resolve or reopen a conversation	API Key (send_messages) or JWT

Webhooks

Method	Endpoint	Description	Auth Required
POST	/api/v1/webhooks	Create webhook	JWT
GET	/api/v1/webhooks	List all webhooks	JWT
GET	/api/v1/webhooks/events	Get supported events	JWT
GET	/api/v1/webhooks/:id	Get webhook by ID	JWT
PUT	/api/v1/webhooks/:id	Update webhook	JWT
DELETE	/api/v1/webhooks/:id	Delete webhook	JWT
GET	/api/v1/webhooks/:id/deliveries	Get webhook deliveries	JWT
POST	/api/v1/webhooks/:id/test	Send a test event	JWT
POST	/api/v1/webhooks/:id/deliveries/:deliveryId/resend	Resend a webhook delivery	JWT

Billing

Method	Endpoint	Description	Auth Required
GET	/api/v1/billing/packages	Get credit packages	None
POST	/api/v1/billing/checkout	Create checkout session	JWT
GET	/api/v1/billing/transactions	Get transaction history	JWT
POST	/api/v1/billing/webhook	Stripe webhook endpoint	Stripe Signature

Request & Response Format

Standard Success Response

All successful API requests return a JSON response with this structure:

{
  "success": true,
  "data": {
    // Response data here
  }
}

Standard Error Response

All error responses follow this structure:

{
  "success": false,
  "error": "Error message description"
}

Pagination

Endpoints that return lists support pagination with these query parameters:

Parameter	Type	Default	Max	Description
page	integer	1	-	Page number
limit	integer	50	100	Items per page

Paginated responses include:

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "total": 150,
      "page": 1,
      "pages": 3,
      "limit": 50
    }
  }
}

Rate Limits

Different endpoints have different rate limits:

Endpoint Type	Rate Limit
API Key endpoints	100 requests/minute
Bulk messaging	10 requests/minute
Authentication endpoints	5 attempts/15 minutes

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1698960000

When rate limited, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": "Rate limit exceeded. Try again in 30 seconds."
}

Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing authentication
402	Payment Required	Insufficient credits
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource not found
409	Conflict	Resource is not in a valid state for this action (e.g. cancelling an already-sent message), or a request with the same Idempotency-Key is still in flight
422	Unprocessable Entity	An Idempotency-Key was reused with a different request body
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred

Message Channels

YeboLink supports multiple messaging channels:

Channel	Value	Description
SMS	sms	Text messages via cellular networks
WhatsApp	whatsapp	Messages via WhatsApp Business API
Email	email	Email messages
Voice	voice	Voice calls (coming soon)

Message Status

Messages can have the following statuses:

Status	Description
scheduled	Message is held until its scheduled_at time; credits reserved
queued	Message queued for sending
sent	Message sent to provider
delivered	Message delivered to recipient
failed	Message failed to send
read	Message read by recipient (WhatsApp only)
cancelled	Scheduled message cancelled before sending; credits refunded

Credit Costs

Different channels have different credit costs:

Channel	Credits per Message/Unit
SMS	1 credit per message (160 chars)
WhatsApp	0.5 credits per message
Email	0.1 credits per email
Voice	2 credits per minute

TIP

Long SMS messages are automatically split into segments. Each segment costs 1 credit. For example, a 320-character SMS will cost 2 credits.

Health Check

Check API health status:

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2025-11-02T12:00:00Z",
  "services": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  }
}

Webhook Signature Verification

All webhook events include a signature header for verification:

X-YeboLink-Signature: sha256=...

See Webhook Verification for implementation details.

Need Help?

• Check our Quick Start Guide
• Read Error Handling documentation
• Contact support: support@yebolink.app