Connect API v2 (Preview)

Connect API v2 is a cleaner, more consistent version of the Connect API. Every time you see a message, you get it back in the same shape with all of its information. Statuses are aligned across sending and receiving, failures come with a reason, and new features such as the events feed are only in v2.

Preview

v2 is in preview. It works today, but details may still change before it is final. The v1 API is unchanged and remains fully supported.

The documentation is in two parts:

• Guides explain how to do something, with examples and the things to watch out for.
• The API reference lists every endpoint with all of its fields, generated from the API itself.

Using the API

• Base URL: https://api.connect.ms/v2
• Authentication: send your API key as a bearer token: Authorization: Bearer { API_KEY }. The X-Api-Key header is not accepted on v2.
• JSON: property names are camelCase and values such as kind and status are lowercase, for example transactional. Times are ISO 8601 in UTC, for example 2026-10-10T09:30:00Z. IDs are strings. Phone numbers are E.164, for example +447700900123.
• Lists return { "data": [...], "nextCursor": "..." }. Pass nextCursor back as cursor to get the next page. It is null on the last page. limit defaults to 50, up to 200.
• Errors are returned as application/problem+json:

{
  "type": "https://api.connect.ms/problems/validation_failed",
  "title": "The request is not valid.",
  "status": 400,
  "detail": "recipient: Must be a valid phone number",
  "errors": { "recipient": ["Must be a valid phone number"] },
  "requestId": "..."
}

Responses of 429 and 503 carry a Retry-After header saying how many seconds to wait.

Versions

Every response has a Connect-Version header with the version of v2 that answered it. The current version is 2026-10-01. To keep using a version when a newer one is released, send it in the Connect-Version request header.

Safe retries

Send an Idempotency-Key header, any unique value up to 255 characters, on a POST or PATCH. If you send the same request again with the same key within 24 hours, you get the first response back instead of a second message, with an Idempotent-Replayed: true header. Reusing a key with a different request is a 422.

What changed from v1

v1	v2
POST /sms/send	POST /v2/sms
DELETE /sms/send/{id}	DELETE /v2/sms/{id}
POST /sms/send/bulk	POST /v2/sms/batches
GET /sms/inbound/sync	GET /v2/events?types=sms.received
Delivery receipt and inbound webhooks	sms.* events
POST /sms/senders	POST /v2/senders

Messages sent with v1 can be looked up with v2, and the other way round.

Email guides

EmailSending domains, testing, sending and tracking email, events and deliverability.

SMS guides

Send SMSSend one message, check its cost and cancel it.

Track SMSStatuses, failure reasons, lookups and conversations.

BatchesSend to many recipients, a contact list or a CSV file.

EventsWebhooks and the events feed.

SendersRequest and check sender names.

TemplatesStore message templates and render them.