Getting Started

This guide walks through the minimum steps to reach a working integration: create an account, authenticate, and send your first message.

Prerequisites

  • An ArelHub account (see Registration)
  • A verified sending subaccount
  • An API key or user JWT token

1. Registration

Create an account using the public registration endpoint. No prior authentication is required.

      
        POST /v1/register 
        Content-Type: application/json
        {
          "email": "dev@example.com",
          "password": "YourPassword123!",
          "organizationName": "Example Corp"
        }

A verification email is sent to the address provided. The account remains in a pending state until email verification is complete.

2. Authenticate

Exchange credentials for a user JWT token.

      
        POST /v1/auth/login
        Content-Type: application/json
        {
          "email": "dev@example.com",
          "password": "YourPassword123!"
        }

Response (200 OK):

      
        {
          "accessToken": "eyJ...",
          "refreshToken": "...",
          "expiresIn": 3600
        }

Include the access token in all subsequent requests:

      Authorization: Bearer eyJ...

For server-to-server integrations, use an API key instead of a JWT. See the Authentication guide for how to create and use API keys.

3. Retrieve your account

      
        GET /v1/accounts/{accountId}
        Authorization: Bearer eyJ...

Your accountId is returned in the login response or accessible via GET /v1/auth/me.

4. Send your first message

Message submission requires an active subaccount and at least one provisioned phone number.

      
        POST /v1/accounts/{accountId}/messages
        Authorization: Bearer eyJ...
        Content-Type: application/json
        {
          "subaccountId": "00000000-0000-0000-0000-000000000001",
          "to": "+15551234567",
          "body": "Hello from ArelHub!"
        }

Response (201 Created):

      
        {
          "messageId": "00000000-0000-0000-0000-000000000002",
          "status": "queued",
          "segmentCount": 1,
          "estimatedCost": 0.008
        }

5. Check delivery status

      
        GET /v1/accounts/{accountId}/messages/{messageId}
        Authorization: Bearer eyJ...

The status field transitions through: queued → dispatched → delivered | failed | undelivered.

Next steps