Core API

Providers.

Providers are the bridge between SendPipe and your messaging services. Connect your own provider credentials, assign priorities, and let SendPipe handle routing, failover, and health monitoring automatically.

Priority-Based Routing

Each provider has a numeric priority within its channel. When you send a message, SendPipe picks the highest-priority healthy provider for that channel. If the send fails, it automatically falls over to the next provider in the priority list.

01Message arrives for a channel (e.g. email).
02SendPipe selects the highest-priority provider with a healthy status.
03On failure, the next provider in the priority list is tried automatically.
04If all providers for the channel are exhausted, the message is moved to the dead-letter queue as FAILED.

Per-Channel Isolation

Failover operates strictly within a single channel per organization. A WhatsApp message that exhausts all WhatsApp providers will never be re-routed to email or SMS. Each channel maintains its own independent provider stack and priority ordering.

Health Scoring

SendPipe continuously monitors provider health based on recent send outcomes. Health status determines whether a provider is eligible for routing.

Status	Condition	Routing behavior
healthy	Error rate below 5% over last 100 sends	Eligible for routing at assigned priority
degraded	Error rate between 5% — 25%	Deprioritized; used only if no healthy providers remain
unhealthy	Error rate above 25% or consecutive failures	Excluded from routing until recovery

Endpoints

GET

/v1/providers

List all providers for the current project, ordered by priority.

POST

/v1/providers

Add a new provider from an installed marketplace package.

PATCH

/v1/providers/:id

Update provider name, credentials, or enabled status.

DELETE

/v1/providers/:id

Remove a provider. Messages in-flight will fail over to the next provider.

POST

/v1/providers/reorder

Set the priority order for all providers within a channel.

Create Provider Body

POST /v1/providers

Request Body

Name	Type	Required	Description
`packageName`	string	Required	Name of the installed marketplace package (e.g. "provider-ses", "provider-meta-cloud").
`name`	string	Required	A friendly display name for this provider instance (e.g. "Production SES").
`credentials`	object	Required	Provider-specific credentials. Schema is defined by the package's getCredentialSchema().

Marketplace Packages

SendPipe ships with 11 provider packages across three channels. Email packages are free and bundled with every organization. WhatsApp and SMS packages are paid add-ons available from the Marketplace.

Email

Free

5 providers

SES, SendGrid, Mailgun, Resend, SMTP

Paid

3 providers

Meta Cloud API, 360dialog, Twilio

SMS

Paid

3 providers

Africa's Talking, Twilio, Termii

Example: Add a Provider

curl -X POST https://sendpipe.org/v1/providers \
  -H "X-SendPipe-Key: sp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "packageName": "provider-ses",
    "name": "Production SES",
    "credentials": {
      "accessKeyId": "AKIA...",
      "secretAccessKey": "wJal...",
      "region": "us-east-1"
    }
  }'

Example: Reorder Providers

Pass an ordered array of provider IDs to set the priority for a channel. The first ID gets the highest priority.

bash

curl -X POST https://sendpipe.org/v1/providers/reorder \
  -H "X-SendPipe-Key: sp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "providerIds": ["prv_primary", "prv_backup", "prv_tertiary"]
  }'