Request a sender
const url = 'https://api.connect.ms/v2/senders';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","sampleContent":"example","countries":["example"],"businessProfileId":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.connect.ms/v2/senders \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "sampleContent": "example", "countries": [ "example" ], "businessProfileId": "example" }'Requests a new sender name. Alphanumeric names are reviewed before approval; a UK mobile number starting 07 is texted a code and becomes awaiting_verification until it is confirmed with the verify endpoint.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”The API version to use, for example 2026-10-01. Defaults to the version set on your API key.
A unique value of up to 255 characters, so a retried request is not acted on twice. Required for keys in Strict API Mode.
Request Bodyrequired
Section titled “Request Bodyrequired”The sender to register.
The sender to register.
object
The sender name: 3 to 11 letters, digits, underscores or spaces, or a UK mobile number starting 07 (a name made only of digits must be one). Surrounding spaces are ignored.
An example of what the sender will be used to send, between 20 and 256 characters. Shown to the reviewer.
The countries to approve the sender for, as ISO 3166-1 alpha-2 codes. Defaults to the workspace’s own country.
The id of the business profile the sender is for. Omit for the workspace’s own business; not used for a mobile number.
Example generated
{ "name": "example", "sampleContent": "example", "countries": [ "example" ], "businessProfileId": "example"}Responses
Section titled “Responses”The sender already existed and is returned, with any new countries added. A mobile number still awaiting verification is texted a new code.
A sender name or virtual number the workspace has requested or can send from.
object
The unique id of the sender.
The kind of sender: sender_name (an alphanumeric name or a UK mobile number) or virtual_number (an inbound number assigned to, or requested by, the workspace).
The sender as it appears on messages: the name, a UK mobile number in 07 format, or a virtual number in E.164 format. A virtual number not yet assigned shows as New virtual number.
The sender status: pending (awaiting review), approved, rejected, awaiting_verification (a UK mobile waiting for the code texted to it) or awaiting_business_verification (held until the business profile it belongs to is verified).
The countries the sender is requested or approved for.
A country the sender is requested or approved for.
object
The country, as an ISO 3166-1 alpha-2 code.
Approval status of a sender for one country: pending, approved or rejected.
True when this is the workspace’s default sender.
The example message supplied when the sender was requested, or null.
The id of the business profile the sender belongs to, or null when none is linked.
When (UTC) the sender was requested.
Example
{ "kind": "sender_name", "status": "pending", "countries": [ { "status": "pending" } ]}The sender was requested. The Location header holds its URL.
A sender name or virtual number the workspace has requested or can send from.
object
The unique id of the sender.
The kind of sender: sender_name (an alphanumeric name or a UK mobile number) or virtual_number (an inbound number assigned to, or requested by, the workspace).
The sender as it appears on messages: the name, a UK mobile number in 07 format, or a virtual number in E.164 format. A virtual number not yet assigned shows as New virtual number.
The sender status: pending (awaiting review), approved, rejected, awaiting_verification (a UK mobile waiting for the code texted to it) or awaiting_business_verification (held until the business profile it belongs to is verified).
The countries the sender is requested or approved for.
A country the sender is requested or approved for.
object
The country, as an ISO 3166-1 alpha-2 code.
Approval status of a sender for one country: pending, approved or rejected.
True when this is the workspace’s default sender.
The example message supplied when the sender was requested, or null.
The id of the business profile the sender belongs to, or null when none is linked.
When (UTC) the sender was requested.
Example
{ "kind": "sender_name", "status": "pending", "countries": [ { "status": "pending" } ]}The request is not valid. The detail field says why, and errors lists any problems by field name.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The API key or bearer token is missing or not valid, or the request signature could not be verified.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The caller is not allowed to do this.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}Another mobile number is still awaiting verification, or this sender was previously rejected.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}This Idempotency-Key was already used for a different request. Use a new key.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}This API key requires an Idempotency-Key header on every POST and PATCH.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}Too many verification requests. Retry after the Retry-After header.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The verification code could not be sent. Retry after the Retry-After header.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}