SMS Gateway API Documentation

Admin endpoints for managing SMS gateways: the provider connections (Infobip and any other connector installed under includes/sms_connectors/), their sender numbers, country restrictions, link-shortening domains, and which user accounts may send through them. These endpoints back the staff Delivery > SMS gateways screens and expose the same class (SMSGatewayManager) it uses.

All commands require the Admin API key (or an admin session) and the DeliveryServers sub-admin privilege. Each handler checks the privilege itself, so it applies even when ADMIN_API_ENFORCE_PRIVILEGES is off, as the classic SMS Gateways screen did. The staff Delivery > SMS gateways screens run on these commands.

Provider credentials are redacted

GatewaySettings holds provider API keys. Every read endpoint returns credential values as the literal string ***REDACTED*** (the same key-name rule system.getsettings applies, plus any connector field declared "type": "password"). smsgateway.update and smsgateway.testconnection accept that literal back as "keep the stored value", so a read-modify-write round trip never has to see, or re-send, the secret. smsgateway.create rejects it, since there is nothing stored to keep.

Nested keys and the API key-lowercasing rule

api.php lowercases every request parameter name, including the keys inside a nested GatewaySettings object. These endpoints match the keys case-insensitively against the connector's declared configuration_fields[].name and store them under the declared name, so {"API_KEY": "..."}, {"api_key": "..."} and {"Api_Key": "..."} are equivalent. Keys the connector does not declare are dropped.

List SMS Connectors

POST /api/v1/smsgateway.connectors.get

API Usage Notes

• Authentication required: Admin API Key
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it)
• Legacy endpoint access via /api.php is also supported
• The credential form is dynamic per connector. Render GatewaySettings from configuration_fields[] (name, label, type, required, default, placeholder, description) and post the values back keyed by name.

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: smsgateway.connectors.get
AdminAPIKey	String	Yes	Admin API key
GatewayType	String	No	Return only this connector type (e.g. infobip)

Example Request

curl -X POST https://example.com/api/v1/smsgateway.connectors.get \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "smsgateway.connectors.get",
    "AdminAPIKey": "your-admin-api-key"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "Connectors": {
    "infobip": {
      "type": "infobip",
      "display_name": "Infobip",
      "version": "1.0.0",
      "description": "Enterprise SMS gateway with global reach and advanced messaging capabilities",
      "configuration_fields": [
        { "name": "api_key", "label": "API Key", "type": "password", "required": true, "description": "Your Infobip API key for authentication" },
        { "name": "base_url", "label": "Base URL", "type": "text", "required": true, "default": "abc.api.infobip.com", "description": "Infobip API base URL (may vary by region)" },
        { "name": "sender", "label": "Default Sender", "type": "text", "required": false, "description": "Default sender ID or phone number" }
      ],
      "supports": { "short_links": true, "sender_id": true, "delivery_reports": true, "two_way": true, "unicode": true, "long_messages": true, "webhooks": true },
      "rate_limits": { "requests_per_second": 50, "messages_per_request": 1000 },
      "status": "stable"
    }
  },
  "TotalConnectors": 1
}

Error Response

{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "Unknown GatewayType. Available: infobip, test"
}

Error Codes

0: Success
1: Unknown GatewayType
99999: Not enough privileges (the admin account does not hold DeliveryServers)

List SMS Gateways

POST /api/v1/smsgateways.get

API Usage Notes

• Authentication required: Admin API Key
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it)
• Legacy endpoint access via /api.php is also supported
• Credentials inside GatewaySettings are returned as ***REDACTED***

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: smsgateways.get
AdminAPIKey	String	Yes	Admin API key
GatewayStatus	String	No	Filter by status: Active or Inactive

Example Request

curl -X POST https://example.com/api/v1/smsgateways.get \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "smsgateways.get",
    "AdminAPIKey": "your-admin-api-key"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "SMSGateways": [
    {
      "GatewayID": 3,
      "GatewayName": "Infobip EU",
      "GatewayType": "infobip",
      "GatewayTypeDisplay": "Infobip",
      "GatewayStatus": "Active",
      "GatewaySettings": { "api_key": "***REDACTED***", "base_url": "abc.api.infobip.com", "sender": "OCTETH", "default_sender": "+15551234567" },
      "DefaultSender": "+15551234567",
      "SenderNumbers": ["+15551234567", "+15557654321"],
      "ShortDomains": ["s.example.com"],
      "CountryRestrictions": ["US", "GB"],
      "MessageConcatenation": 5,
      "IsGlobal": 0,
      "AssignedUserCount": 2,
      "CreatedAt": "2026-09-04 10:00:00",
      "UpdatedAt": "2026-09-04 10:30:00"
    }
  ],
  "TotalSMSGateways": 1
}

Error Response

{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "Invalid GatewayStatus. Allowed: Active, Inactive"
}

Error Codes

0: Success
1: Invalid GatewayStatus
99999: Not enough privileges (the admin account does not hold DeliveryServers)

Get an SMS Gateway

POST /api/v1/smsgateway.get

API Usage Notes

• Authentication required: Admin API Key
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it)
• Legacy endpoint access via /api.php is also supported
• Credentials inside GatewaySettings are returned as ***REDACTED***; smsgateway.update accepts that value back to keep the stored secret

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: smsgateway.get
AdminAPIKey	String	Yes	Admin API key
GatewayID	Integer	Yes	ID of the gateway

Example Request

curl -X POST https://example.com/api/v1/smsgateway.get \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "smsgateway.get",
    "AdminAPIKey": "your-admin-api-key",
    "GatewayID": 3
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "SMSGateway": {
    "GatewayID": 3,
    "GatewayName": "Infobip EU",
    "GatewayType": "infobip",
    "GatewayTypeDisplay": "Infobip",
    "GatewayStatus": "Active",
    "GatewaySettings": { "api_key": "***REDACTED***", "base_url": "abc.api.infobip.com", "sender": "OCTETH", "default_sender": "+15551234567" },
    "DefaultSender": "+15551234567",
    "SenderNumbers": ["+15551234567", "+15557654321"],
    "ShortDomains": ["s.example.com"],
    "CountryRestrictions": ["US", "GB"],
    "MessageConcatenation": 5,
    "IsGlobal": 0,
    "AssignedUserCount": 2,
    "CreatedAt": "2026-09-04 10:00:00",
    "UpdatedAt": "2026-09-04 10:30:00"
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": 2,
  "ErrorText": "SMS gateway not found"
}

Error Codes

0: Success
1: Missing or invalid GatewayID
2: SMS gateway not found
99999: Not enough privileges (the admin account does not hold DeliveryServers)

Create an SMS Gateway

POST /api/v1/smsgateway.create

API Usage Notes

• Authentication required: Admin API Key
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it)
• Legacy endpoint access via /api.php is also supported
• Not available in demo mode
• GatewaySettings keys are the connector's configuration_fields[].name from smsgateway.connectors.get; required ones must be present and non-empty
• DefaultSender is stored inside GatewaySettings as default_sender (the same place the admin screen stores it) and must be one of SenderNumbers
• List parameters (SenderNumbers, ShortDomains, CountryRestrictions, UserIDs) accept a JSON array or a newline/comma separated string
• A non-global gateway (IsGlobal=0) is only usable by the users assigned to it; pass UserIDs here or call smsgateway.users.assign afterwards

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: smsgateway.create
AdminAPIKey	String	Yes	Admin API key
GatewayName	String	Yes	Display name, 3 to 255 characters
GatewayType	String	Yes	Connector type, one of the keys returned by smsgateway.connectors.get
GatewayStatus	String	No	Active (default) or Inactive
GatewaySettings	Object	Yes	Per-connector configuration keyed by field name
SenderNumbers	Array	No	Sender numbers; each must match +?[1-9][0-9]{6,14}
ShortDomains	Array	No	Link-shortening domains. ASCII hostnames such as go.example.com, at least two labels, no scheme, port or path. Convert an internationalized domain to its punycode form
CountryRestrictions	Array	No	Two-letter country codes the gateway may send to; stored upper-cased
MessageConcatenation	Integer	No	Maximum SMS parts per message, 1 to 10 (default 10)
IsGlobal	Boolean	No	1 = available to every user; 0 (default) = only to assigned users
DefaultSender	String	No	Default sender number; must be one of SenderNumbers
UserIDs	Array	No	Users to assign (only when IsGlobal=0)

Example Request

curl -X POST https://example.com/api/v1/smsgateway.create \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "smsgateway.create",
    "AdminAPIKey": "your-admin-api-key",
    "GatewayName": "Infobip EU",
    "GatewayType": "infobip",
    "GatewayStatus": "Active",
    "GatewaySettings": { "api_key": "your-infobip-key", "base_url": "abc.api.infobip.com", "sender": "OCTETH" },
    "SenderNumbers": ["+15551234567", "+15557654321"],
    "ShortDomains": ["s.example.com"],
    "CountryRestrictions": ["US", "GB"],
    "MessageConcatenation": 5,
    "DefaultSender": "+15551234567",
    "IsGlobal": 0,
    "UserIDs": [12, 15]
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "GatewayID": 3,
  "SMSGateway": {
    "GatewayID": 3,
    "GatewayName": "Infobip EU",
    "GatewayType": "infobip",
    "GatewayStatus": "Active",
    "GatewaySettings": { "api_key": "***REDACTED***", "base_url": "abc.api.infobip.com", "sender": "OCTETH", "default_sender": "+15551234567" },
    "DefaultSender": "+15551234567",
    "SenderNumbers": ["+15551234567", "+15557654321"],
    "ShortDomains": ["s.example.com"],
    "CountryRestrictions": ["US", "GB"],
    "MessageConcatenation": 5,
    "IsGlobal": 0,
    "AssignedUserCount": 2
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": 8,
  "ErrorText": "Missing required GatewaySettings field(s): API Key"
}

Error Codes

0: Success
1: Missing GatewayName
2: GatewayName must be between 3 and 255 characters
3: Missing GatewayType
4: Unknown GatewayType
5: Invalid GatewayStatus
6: GatewaySettings missing or not an object
7: GatewaySettings contains the redaction marker (nothing stored to keep on create)
8: Missing required connector field(s) (ErrorText lists them)
9: Invalid SenderNumbers (ErrorText lists them)
10: Invalid CountryRestrictions (ErrorText lists them)
11: Invalid MessageConcatenation (must be 1 to 10)
12: DefaultSender is not one of SenderNumbers
13: UserIDs given for a global gateway
14: Unknown UserIDs (ErrorText lists them)
15: UserIDs outside the user groups this admin account may access
16: Gateway could not be created
17: Users could not be assigned to the new gateway (the gateway is not created)
18: Invalid ShortDomains: an entry is not an ASCII hostname (ErrorText lists them)
99999: Not enough privileges (the admin account does not hold DeliveryServers)

Update an SMS Gateway

POST /api/v1/smsgateway.update

API Usage Notes

• Authentication required: Admin API Key
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it)
• Legacy endpoint access via /api.php is also supported
• Not available in demo mode
• Partial update: only the parameters present in the request change
• GatewaySettings is itself partial: keys omitted keep their stored value, a key equal to ***REDACTED*** keeps its stored value, any other key is replaced (send "" to clear one). Required connector fields are checked on the resulting object, so a partial update can never leave the gateway without a credential it needs
• Changing GatewayType requires a complete GatewaySettings for the new connector with no redaction markers
• Setting IsGlobal=1 clears all user assignments
• A sub-admin restricted to specific user groups may only name users in those groups; existing assignments outside its scope are preserved

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: smsgateway.update
AdminAPIKey	String	Yes	Admin API key
GatewayID	Integer	Yes	ID of the gateway
GatewayName	String	No	Display name, 3 to 255 characters
GatewayType	String	No	New connector type (see notes)
GatewayStatus	String	No	Active or Inactive
GatewaySettings	Object	No	Per-connector configuration, partial (see notes)
SenderNumbers	Array	No	Replaces the sender number list
ShortDomains	Array	No	Replaces the short domain list. ASCII hostnames such as go.example.com, at least two labels, no scheme, port or path. Convert an internationalized domain to its punycode form
CountryRestrictions	Array	No	Replaces the country restriction list
MessageConcatenation	Integer	No	1 to 10
IsGlobal	Boolean	No	1 or 0
DefaultSender	String	No	Must be one of the effective SenderNumbers; "" clears it
UserIDs	Array	No	Replaces the assignment set (only when the gateway is non-global); "" clears it

Example Request

curl -X POST https://example.com/api/v1/smsgateway.update \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "smsgateway.update",
    "AdminAPIKey": "your-admin-api-key",
    "GatewayID": 3,
    "GatewayName": "Infobip EU (primary)",
    "GatewaySettings": { "api_key": "***REDACTED***", "base_url": "eu.api.infobip.com" },
    "MessageConcatenation": 3
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "SMSGateway": {
    "GatewayID": 3,
    "GatewayName": "Infobip EU (primary)",
    "GatewayType": "infobip",
    "GatewayStatus": "Active",
    "GatewaySettings": { "api_key": "***REDACTED***", "base_url": "eu.api.infobip.com", "sender": "OCTETH", "default_sender": "+15551234567" },
    "DefaultSender": "+15551234567",
    "SenderNumbers": ["+15551234567", "+15557654321"],
    "ShortDomains": ["s.example.com"],
    "CountryRestrictions": ["US", "GB"],
    "MessageConcatenation": 3,
    "IsGlobal": 0,
    "AssignedUserCount": 2
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": 11,
  "ErrorText": "DefaultSender must be one of SenderNumbers"
}

Error Codes

0: Success
1: Missing or invalid GatewayID
2: SMS gateway not found
3: GatewayName must be between 3 and 255 characters
4: Unknown GatewayType
5: Invalid GatewayStatus
6: GatewaySettings not an object, or missing while GatewayType changes
7: Missing required connector field(s) on the resulting settings (ErrorText lists them)
8: Invalid SenderNumbers (ErrorText lists them)
9: Invalid CountryRestrictions (ErrorText lists them)
10: Invalid MessageConcatenation (must be 1 to 10)
11: DefaultSender is not one of SenderNumbers
12: UserIDs given for a global gateway
13: Unknown UserIDs (ErrorText lists them)
14: UserIDs outside the user groups this admin account may access
15: Redaction marker not allowed when GatewayType changes
16: Gateway could not be updated
17: Gateway updated but its user assignments could not be saved
18: Invalid ShortDomains: an entry is not an ASCII hostname (ErrorText lists them)
99999: Not enough privileges (the admin account does not hold DeliveryServers)

Delete SMS Gateways

POST /api/v1/smsgateways.delete

API Usage Notes

• Authentication required: Admin API Key
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it)
• Legacy endpoint access via /api.php is also supported
• Not available in demo mode
• Deletes the gateways and their user assignments. Unknown ids in the list are ignored; the response lists what was actually deleted

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: smsgateways.delete
AdminAPIKey	String	Yes	Admin API key
GatewayIDs	String or Array	Yes	Comma-separated list or JSON array of gateway ids

Example Request

curl -X POST https://example.com/api/v1/smsgateways.delete \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "smsgateways.delete",
    "AdminAPIKey": "your-admin-api-key",
    "GatewayIDs": "3,4"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "DeletedGatewayIDs": [3, 4],
  "TotalDeleted": 2
}

Error Response

{
  "Success": false,
  "ErrorCode": 2,
  "ErrorText": "None of the given GatewayIDs exist"
}

Error Codes

0: Success
1: Missing or invalid GatewayIDs
2: None of the given GatewayIDs exist
3: Gateways could not be deleted
99999: Not enough privileges (the admin account does not hold DeliveryServers)

Test an SMS Gateway Connection

POST /api/v1/smsgateway.testconnection

API Usage Notes

• Authentication required: Admin API Key
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it)
• Legacy endpoint access via /api.php is also supported
• Runs the provider's live credential check. Nothing is persisted
• Two modes: GatewayID tests the saved gateway (an optional GatewaySettings overrides stored values first, markers keep the stored value); GatewayType plus GatewaySettings tests unsaved credentials
• Rate limited to 5 provider calls per hour per admin, shared with the admin screen's Test Connection button. Requests rejected by validation (codes 1 to 5) do not count

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: smsgateway.testconnection
AdminAPIKey	String	Yes	Admin API key
GatewayID	Integer	Conditional	Saved gateway to test
GatewayType	String	Conditional	Connector type for an unsaved test (ignored when GatewayID is given)
GatewaySettings	Object	Conditional	Credentials to test, or overrides for the saved gateway

Example Request

curl -X POST https://example.com/api/v1/smsgateway.testconnection \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "smsgateway.testconnection",
    "AdminAPIKey": "your-admin-api-key",
    "GatewayType": "infobip",
    "GatewaySettings": { "api_key": "your-infobip-key", "base_url": "abc.api.infobip.com" }
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "GatewayType": "infobip",
  "Message": "Connection successful",
  "Details": {},
  "RemainingTests": 4
}

Error Response

{
  "Success": false,
  "ErrorCode": 6,
  "ErrorText": "Rate limit exceeded. Please wait 42 minute(s) before testing again.",
  "RetryAfter": 2520,
  "RemainingTests": 0
}

Error Codes

0: Success
1: Neither GatewayID nor GatewayType given
2: SMS gateway not found
3: Unknown GatewayType
4: GatewaySettings not an object
5: Missing required connector field(s) (ErrorText lists them)
6: Rate limit exceeded (RetryAfter seconds and RemainingTests are returned)
7: Connection test failed (ErrorText carries the provider message, Details any extra data)
99999: Not enough privileges (the admin account does not hold DeliveryServers)

List Users Assigned to an SMS Gateway

POST /api/v1/smsgateway.users.get

API Usage Notes

• Authentication required: Admin API Key
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it)
• Legacy endpoint access via /api.php is also supported
• Only meaningful for non-global gateways (IsGlobal=0); a global gateway always returns an empty list
• A sub-admin restricted to specific user groups only sees users in those groups; TotalAssignedUsers is the unfiltered count

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: smsgateway.users.get
AdminAPIKey	String	Yes	Admin API key
GatewayID	Integer	Yes	ID of the gateway

Example Request

curl -X POST https://example.com/api/v1/smsgateway.users.get \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "smsgateway.users.get",
    "AdminAPIKey": "your-admin-api-key",
    "GatewayID": 3
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "GatewayID": 3,
  "IsGlobal": 0,
  "Users": [
    { "UserID": 12, "Username": "acme", "EmailAddress": "ops@acme.example", "RelUserGroupID": 2, "AssignedAt": "2026-09-04 10:00:00" }
  ],
  "TotalUsers": 1,
  "TotalAssignedUsers": 1
}

Error Response

{
  "Success": false,
  "ErrorCode": 2,
  "ErrorText": "SMS gateway not found"
}

Error Codes

0: Success
1: Missing or invalid GatewayID
2: SMS gateway not found
99999: Not enough privileges (the admin account does not hold DeliveryServers)

Assign Users to an SMS Gateway

POST /api/v1/smsgateway.users.assign

API Usage Notes

• Authentication required: Admin API Key
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it)
• Legacy endpoint access via /api.php is also supported
• Not available in demo mode
• Replaces the whole assignment set. Pass an empty UserIDs to clear it
• Only for non-global gateways; set IsGlobal=0 with smsgateway.update first
• A sub-admin restricted to specific user groups may only name users in those groups; existing assignments outside its scope are preserved rather than dropped

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: smsgateway.users.assign
AdminAPIKey	String	Yes	Admin API key
GatewayID	Integer	Yes	ID of the gateway
UserIDs	String or Array	Yes	Comma-separated list or JSON array of user ids; empty clears all assignments

Example Request

curl -X POST https://example.com/api/v1/smsgateway.users.assign \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "smsgateway.users.assign",
    "AdminAPIKey": "your-admin-api-key",
    "GatewayID": 3,
    "UserIDs": [12, 15]
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "GatewayID": 3,
  "AssignedUserIDs": [12, 15],
  "TotalAssignedUsers": 2
}

Error Response

{
  "Success": false,
  "ErrorCode": 4,
  "ErrorText": "This gateway is global (IsGlobal=1); per-user assignment does not apply. Set IsGlobal=0 via smsgateway.update first"
}

Error Codes

0: Success
1: Missing or invalid GatewayID
2: SMS gateway not found
3: UserIDs parameter missing (pass an empty value to clear)
4: Gateway is global; per-user assignment does not apply
5: Unknown UserIDs (ErrorText lists them)
6: UserIDs outside the user groups this admin account may access
7: Assignment could not be saved
99999: Not enough privileges (the admin account does not hold DeliveryServers)

Get What Uses an SMS Gateway

POST /api/v1/admin.smsgateway.references.get

API Usage Notes

• Authentication required: Admin API Key or an admin session
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it)
• Read only. Call it before deleting a gateway or setting it Inactive
• Campaigns lists the SMS campaigns that are Scheduled, Queueing, Sending or Paused on the gateway; Journeys the journeys with a Send SMS step that sends through it
• HasSoleInboundOwner is 1 when the gateway is not global and has exactly one assigned account. That account is credited with the inbound replies that match no subscriber, so changing the assignment changes who sees them
• A sub-admin limited to some user groups gets only the rows of accounts in those groups. TotalCampaigns and TotalJourneys count every row, and SoleInboundOwner is null when the owner is outside those groups
• Added in v6.0.2 (#3551)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: admin.smsgateway.references.get
AdminAPIKey	String	Yes	Admin API key
GatewayID	Integer	Yes	ID of the gateway

Example Request

curl -X POST https://example.com/api/v1/admin.smsgateway.references.get \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "admin.smsgateway.references.get",
    "AdminAPIKey": "your-admin-api-key",
    "GatewayID": 3
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "GatewayID": 3,
  "IsGlobal": 0,
  "Campaigns": [
    { "CampaignID": 31, "CampaignName": "Spring sale", "Status": "Scheduled", "UserID": 12, "Username": "acme" }
  ],
  "TotalCampaigns": 1,
  "Journeys": [
    { "JourneyID": 8, "JourneyName": "Welcome series", "Status": "Enabled", "UserID": 12, "Username": "acme" }
  ],
  "TotalJourneys": 1,
  "TotalAssignedUsers": 1,
  "HasSoleInboundOwner": 1,
  "SoleInboundOwner": { "UserID": 12, "Username": "acme" }
}

Error Response

{
  "Success": false,
  "ErrorCode": 2,
  "ErrorText": "SMS gateway not found"
}

Error Codes

0: Success
1: Missing or invalid GatewayID
2: SMS gateway not found
3: The references could not be read
99999: Not enough privileges (the admin account does not hold DeliveryServers)

Search Accounts to Assign to an SMS Gateway

POST /api/v1/admin.smsgateway.users.search

API Usage Notes

• Authentication required: Admin API Key or an admin session
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it). It does not need User.Browse, which Users.Get does
• Read only. Returns enabled accounts whose username, email address, first or last name or company contains Keyword, ordered by username. % and _ in the keyword are matched literally
• A sub-admin limited to some user groups finds only the accounts in those groups
• Added in v6.0.2 (#3551)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: admin.smsgateway.users.search
AdminAPIKey	String	Yes	Admin API key
Keyword	String	Yes	At least 2 characters
Limit	Integer	No	Most accounts returned. Default 8, at most 25

Example Request

curl -X POST https://example.com/api/v1/admin.smsgateway.users.search \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "admin.smsgateway.users.search",
    "AdminAPIKey": "your-admin-api-key",
    "Keyword": "acme"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "Users": [
    { "UserID": 12, "Username": "acme", "EmailAddress": "ops@acme.example", "FirstName": "Ada", "LastName": "Ops", "CompanyName": "Acme Ltd" }
  ],
  "TotalUsers": 1
}

Error Response

{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "Keyword must be at least 2 characters"
}

Error Codes

0: Success
1: Keyword must be at least 2 characters
2: The accounts could not be read
99999: Not enough privileges (the admin account does not hold DeliveryServers)

Get the Webhook Settings of an SMS Gateway

POST /api/v1/admin.smsgateway.webhook.get

API Usage Notes

• Authentication required: Admin API Key or an admin session
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it)
• Without Reveal, the answer carries no secret: whether delivery reports must carry the secret, whether a secret is set, and the other gateways on the same provider account (AccountGroupGateways), which share one set of callback URLs
• With Reveal=1 it adds WebhookSecret and the two callback URLs, which embed it. Each such read is logged at INFO. The URLs are empty when the install has no public callback address (SMS_DLR_NOTIFY_BASE_URL or APP_URL)
• Added in v6.0.2 (#3551)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: admin.smsgateway.webhook.get
AdminAPIKey	String	Yes	Admin API key
GatewayID	Integer	Yes	ID of the gateway
Reveal	Boolean	No	1 to return the secret and the callback URLs. Default: not returned

Example Request

curl -X POST https://example.com/api/v1/admin.smsgateway.webhook.get \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "admin.smsgateway.webhook.get",
    "AdminAPIKey": "your-admin-api-key",
    "GatewayID": 3,
    "Reveal": 1
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "GatewayID": 3,
  "EnforceWebhookSecret": 1,
  "HasWebhookSecret": 1,
  "AccountGroupGateways": [
    { "GatewayID": 4, "GatewayName": "Xeebi backup" }
  ],
  "WebhookSecret": "5f2c9a7e...c3f",
  "DeliveryReportURL": "https://example.com/app/public/sms_deliveryreports/delivery_report/xeebi/<encrypted-id>/<secret>",
  "InboundURL": "https://example.com/app/public/sms_inbound/receive/xeebi/<encrypted-id>/<secret>"
}

Error Response

{
  "Success": false,
  "ErrorCode": 2,
  "ErrorText": "SMS gateway not found"
}

Error Codes

0: Success
1: Missing or invalid GatewayID
2: SMS gateway not found
99999: Not enough privileges (the admin account does not hold DeliveryServers)

Rotate the Webhook Secret of an SMS Gateway

POST /api/v1/admin.smsgateway.webhook.rotate

API Usage Notes

• Authentication required: Admin API Key or an admin session
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it), before the demo-mode refusal
• Not available in demo mode
• Replaces the secret. Both callback URLs carry it, so they change at once, and the provider is refused until it is given the new ones. The answer is the only copy of the new values short of a later admin.smsgateway.webhook.get with Reveal=1. Each rotation is logged at INFO
• Added in v6.0.2 (#3551)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: admin.smsgateway.webhook.rotate
AdminAPIKey	String	Yes	Admin API key
GatewayID	Integer	Yes	ID of the gateway

Example Request

curl -X POST https://example.com/api/v1/admin.smsgateway.webhook.rotate \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "admin.smsgateway.webhook.rotate",
    "AdminAPIKey": "your-admin-api-key",
    "GatewayID": 3
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "GatewayID": 3,
  "WebhookSecret": "9b1d...7e4a",
  "DeliveryReportURL": "https://example.com/app/public/sms_deliveryreports/delivery_report/xeebi/<encrypted-id>/<new-secret>",
  "InboundURL": "https://example.com/app/public/sms_inbound/receive/xeebi/<encrypted-id>/<new-secret>"
}

Error Response

{
  "Success": false,
  "ErrorCode": 3,
  "ErrorText": "The webhook secret could not be rotated. Check the application log for details"
}

Error Codes

0: Success
1: Missing or invalid GatewayID
2: SMS gateway not found
3: The secret could not be generated or saved
99999: Not enough privileges (the admin account does not hold DeliveryServers)
NOT AVAILABLE IN DEMO MODE.

Require the Webhook Secret on Delivery Reports

POST /api/v1/admin.smsgateway.webhook.update

API Usage Notes

• Authentication required: Admin API Key or an admin session
• Privilege: DeliveryServers, checked even when ADMIN_API_ENFORCE_PRIVILEGES is off (answers 99999 without it), before the demo-mode refusal
• Not available in demo mode
• With EnforceWebhookSecret=0, delivery reports are also accepted on the older URL without the secret, which gateways created before webhook secrets existed still use. Inbound messages always require the secret, whatever this is set to. New gateways start with it on
• Added in v6.0.2 (#3551)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: admin.smsgateway.webhook.update
AdminAPIKey	String	Yes	Admin API key
GatewayID	Integer	Yes	ID of the gateway
EnforceWebhookSecret	Boolean	Yes	1 or true to require the secret on delivery reports, 0 or false to also accept the older URL

Example Request

curl -X POST https://example.com/api/v1/admin.smsgateway.webhook.update \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "admin.smsgateway.webhook.update",
    "AdminAPIKey": "your-admin-api-key",
    "GatewayID": 3,
    "EnforceWebhookSecret": 1
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "GatewayID": 3,
  "EnforceWebhookSecret": 1
}

Error Response

{
  "Success": false,
  "ErrorCode": 3,
  "ErrorText": "Missing or invalid EnforceWebhookSecret. Allowed: 1, 0, true, false"
}

Error Codes

0: Success
1: Missing or invalid GatewayID
2: SMS gateway not found
3: Missing or invalid EnforceWebhookSecret
4: The setting could not be saved
99999: Not enough privileges (the admin account does not hold DeliveryServers)
NOT AVAILABLE IN DEMO MODE.