Sender IDs

A Sender ID is the name or number the recipient sees as the message sender — the identity on whose behalf a message is delivered. Every POST /messages call (and every step of a POST /omnimessages cascade) carries a senderId that must:

  1. Belong to your company (the company that owns the API key),
  2. Be registered for the requested channel, and
  3. Be in Active status (status: 2).

If you have not registered your own Sender ID yet, a generic default sender is used — you can start sending before approval completes, and switch to your branded Sender ID once it is Active.

Per-channel binding

Each Sender ID is bound to exactly one channel. An SMS Sender cannot be used on another channel — sending with a Sender that is not registered for the requested channel fails with 404. Register a separate Sender per channel you use.

Getting a Sender ID approved

Sender IDs are created and managed in the client portal; the API exposes a read-only view via GET /senders.

  1. In the client portal, open Assets → Sender IDs.
  2. Create the sender and submit it for approval.
  3. Wait for approval. Approval times vary by country and operator — some destinations approve quickly, others take longer and may have extra registration requirements, so start this step early.
  4. Confirm the destination is open for your account (the required operators are enabled and routed) — check with your account manager.

Once Active, a Sender ID can be reused indefinitely. Edits that change the recipient-visible profile (such as the display name) require re-approval.

Statuses

GET /senders returns a numeric status per Sender:

Code Status Can send? Meaning
-1 Blocked No Blocked by the platform owner.
0 Draft No Saved in the portal but not yet submitted for approval.
1 In tests Limited Approved for testing; typically restricted to test recipients.
2 Active Yes Fully approved and operational — the only status that allows production sending.

The portal additionally shows intermediate workflow stages (Submitted, In progress, Done, Rejected, Canceled, Testing); the API collapses these into the four numeric codes above according to whether sending is currently allowed.

Lifecycle

stateDiagram-v2
    [*] --> Draft: created in portal
    Draft --> Submitted: submit for approval
    Submitted --> InProgress: review starts
    InProgress --> Testing: marked for testing
    InProgress --> Active: approved
    Testing --> Active: passes
    InProgress --> Rejected: rejected
    Active --> Blocked: blocked by platform owner
    Blocked --> Active: unblocked
    Active --> Canceled: cancelled by user
    Rejected --> [*]
    Canceled --> [*]

There is no webhook for approval status changes — poll GET /senders and check for status: 2 before switching production traffic to a new Sender.

Key fields (GET /senders)

Field Type Meaning
senderId string The value to pass as senderId in send requests (e.g. Routeon, 1112223334).
displayName string Human-readable label shown to recipients where the channel supports it.
channel integer The channel this Sender is registered for — see Channels.
status integer Status code from the table above.
webhookUrl string Delivery-status webhook configured for this Sender — used when the send request itself carries no webhook field.

The list has no server-side filters; select by channel and status client-side. Creation and edits are portal-only — there are no write endpoints for Senders in the API.

See the API Reference: GET /senders.