Skip to content
Akedly
Command reference

BYO SMS

Akedly CLI command reference: BYO SMS.

Build with AI agents

byo-sms countries

Read the currently routable country catalog for BYO-SMS coverage planning.

When to use

  • Before integration country configuration.

How it works

  1. Reads routable country source; cold catalog may be temporarily unavailable.

Prerequisites

  • Entitlement and granular pricing.

Expected outcome

Country catalog.

Next steps

  • Use only offered codes; retry catalog outage later.

Usage

sh
akedly byo-sms countries

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms countries" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:read.

Server request: GET /byo-sms/countries.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

List the routable country catalog. A cold catalog returns HTTP 503 COUNTRY_CATALOG_UNAVAILABLE; retry later. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are supported.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Before integration country configuration.

sh
akedly byo-sms countries

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": [
    {
      "isoCode": "EG",
      "name": "Egypt"
    },
    {
      "isoCode": "US",
      "name": "United States"
    }
  ]
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms countries

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The endpoint returns data as an array of country objects with isoCode and name. Schema permits API extensions per item.

Examples are synthetic and the routable country list can change.

Common error guidance.

byo-sms list

Review account BYO-SMS routes, provider, coverage and routing status.

When to use

  • Choose an id or recover uncertain write.

How it works

  1. Lists newest-first, strips stored secrets; visible step fields can still contain literal credentials. Header/query serialize as {} even if configured.
  2. Stored countries [] (and a sole ALL sentinel) means catch-all; a non-empty country list limits the route to those codes.

Prerequisites

  • Entitlement and granular pricing.

Expected outcome

Integration array; visibility can hide steps/fees; active does not imply effective traffic routing.

Next steps

  • Inspect with get, and review pipeline/account routing independently.

Usage

sh
akedly byo-sms list

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms list" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:read.

Server request: GET /byo-sms/integrations.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Sensitive output: echo-scrub. echo-scrub masks secret-shaped text, credential fields, secret query parameters and JSON secret fields inside strings in the response, such as a webhook receiver echo or BYO-SMS steps; keep the output private anyway.

Full command details

List all your integrations, newest first, without pagination or filters. The server strips secrets and vodafoneSetup, exposing secretNames instead of secret values, but visible steps are returned verbatim and may contain literal credentials (for example in auth, url or bodyTemplate); keep output private. Each step's headers and query currently come back as {} even when values are saved, so an empty headers or query object does not show the saved configuration. Member permissions can hide steps or fees (stepsVisible/feeVisible). Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are supported. active does not mean sends use this integration: routing follows each pipeline setting (akedly pipelines get <id> -> data.byoSms: inherit|on|off); inherit uses the account switch (akedly whoami -> user.byoSmsEnabled, set by Akedly), while on/off override it. Vodafone rows in byo-sms list also report routingEnabled.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Choose an id or recover uncertain write.

sh
akedly byo-sms list

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": [
    {
      "_id": "64b000000000000000000001",
      "userID": "64b000000000000000000010",
      "pipelineID": null,
      "name": "Synthetic route",
      "description": null,
      "uid": "11111111-1111-4111-8111-111111111111",
      "providerKey": "generic",
      "adapterVersion": null,
      "providerConfig": {
        "senderName": null
      },
      "countries": [
        "EG"
      ],
      "steps": [
        {
          "method": "POST",
          "url": "https://sms.example.invalid/send",
          "headers": {},
          "query": {},
          "bodyType": "json",
          "bodyTemplate": "{\"to\":\"{{phone}}\",\"text\":\"{{otpMessage}}\",\"key\":\"{{secrets.apiKey}}\"}",
          "auth": {
            "type": "none",
            "token": null,
            "username": null,
            "password": "[REDACTED — synthetic secret omitted]",
            "headerName": null,
            "headerValue": null
          },
          "timeoutMs": 3000,
          "retryCount": 0,
          "isSendStep": true,
          "successAssertion": {
            "statusIn": [
              200,
              201,
              202
            ],
            "jsonPathEquals": null,
            "bodyMatches": null
          },
          "extract": []
        }
      ],
      "onFailure": "fallbackToAkedly",
      "feeOverride": null,
      "active": false,
      "liveAnnouncedAt": null,
      "testPhone": null,
      "testStatus": {
        "passed": false,
        "lastTestedAt": null,
        "lastResultSummary": null,
        "providerSmsId": null,
        "certainty": null,
        "failureCategory": null,
        "lastTestKey": null,
        "contractFingerprint": null
      },
      "configHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "stepsVisible": true,
      "feeVisible": true,
      "secretNames": [
        "apiKey"
      ],
      "resolvedFeeEGP": 0.25
    }
  ]
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms list

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Sanitizer removes secret values and Vodafone private setup. steps/feeOverride may be omitted by member permission; stepsVisible and feeVisible state visibility. Step headers/query serialize as empty objects even if configured; do not rebuild replacement config from that view.

A Vodafone integration carries structured readiness fields; list includes routingEnabled only for Vodafone rows and can include resolvedFeeEGP when fee visibility is granted. API may append extension fields.

Common error guidance.

byo-sms get

Inspect one owned route’s provider setup, test state, coverage, fee and routing readiness.

When to use

  • Before editing/testing/activating or retry recovery.

How it works

  1. Reads sanitized route; visible step text may leak inline credentials and headers/query are not faithfully echoed.
  2. Stored countries [] (and a sole ALL sentinel) means catch-all; a non-empty country list limits the route to those codes.

Prerequisites

  • Owned id; entitlement.

Expected outcome

One decorated integration.

Next steps

  • Never reconstruct a replacement step file from redacted/incomplete response.

Usage

sh
akedly byo-sms get <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms get" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the id from akedly byo-sms list.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:read.

Server request: GET /byo-sms/integrations/:id.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Sensitive output: echo-scrub. echo-scrub masks secret-shaped text, credential fields, secret query parameters and JSON secret fields inside strings in the response, such as a webhook receiver echo or BYO-SMS steps; keep the output private anyway.

Full command details

Read one of your integrations. The server strips secrets and vodafoneSetup, exposing secretNames instead of secret values, but visible steps are returned verbatim and may contain literal credentials (for example in auth, url or bodyTemplate); keep output private. Each step's headers and query currently come back as {} even when values are saved, so an empty headers or query object does not show the saved configuration. Member permissions can hide steps or fees (stepsVisible/feeVisible). Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are supported. active does not mean sends use this integration: routing follows each pipeline setting (akedly pipelines get <id> -> data.byoSms: inherit|on|off); inherit uses the account switch (akedly whoami -> user.byoSmsEnabled, set by Akedly), while on/off override it. Vodafone rows in byo-sms list also report routingEnabled.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Before editing/testing/activating or retry recovery.

sh
akedly byo-sms get 64b000000000000000000001

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000001",
    "userID": "64b000000000000000000010",
    "pipelineID": null,
    "name": "Synthetic route",
    "description": null,
    "uid": "11111111-1111-4111-8111-111111111111",
    "providerKey": "generic",
    "adapterVersion": null,
    "providerConfig": {
      "senderName": null
    },
    "countries": [
      "EG"
    ],
    "steps": [
      {
        "method": "POST",
        "url": "https://sms.example.invalid/send",
        "headers": {},
        "query": {},
        "bodyType": "json",
        "bodyTemplate": "{\"to\":\"{{phone}}\",\"text\":\"{{otpMessage}}\",\"key\":\"{{secrets.apiKey}}\"}",
        "auth": {
          "type": "none",
          "token": null,
          "username": null,
          "password": "[REDACTED — synthetic secret omitted]",
          "headerName": null,
          "headerValue": null
        },
        "timeoutMs": 3000,
        "retryCount": 0,
        "isSendStep": true,
        "successAssertion": {
          "statusIn": [
            200,
            201,
            202
          ],
          "jsonPathEquals": null,
          "bodyMatches": null
        },
        "extract": []
      }
    ],
    "onFailure": "fallbackToAkedly",
    "feeOverride": null,
    "active": false,
    "liveAnnouncedAt": null,
    "testPhone": null,
    "testStatus": {
      "passed": false,
      "lastTestedAt": null,
      "lastResultSummary": null,
      "providerSmsId": null,
      "certainty": null,
      "failureCategory": null,
      "lastTestKey": null,
      "contractFingerprint": null
    },
    "configHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "stepsVisible": true,
    "feeVisible": true,
    "secretNames": [
      "apiKey"
    ]
  }
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms get <id>

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Sanitizer removes secret values and Vodafone private setup. steps/feeOverride may be omitted by member permission; stepsVisible and feeVisible state visibility. Step headers/query serialize as empty objects even if configured; do not rebuild replacement config from that view.

A Vodafone integration carries structured readiness fields; list includes routingEnabled only for Vodafone rows and can include resolvedFeeEGP when fee visibility is granted. API may append extension fields.

Common error guidance.

byo-sms fee

Quote account registry resolved utility-SMS fee; no send or charge.

When to use

  • Explain account pricing; mixed fees yield null singular fee and min/max range.

How it works

  1. Uses shared server resolver across active tested account integrations.

Prerequisites

  • Entitlement, granular pricing, ana_rates_explorer read.

Expected outcome

feeEGP is the resolved account price when one price applies; when active tested account-registry routes have different prices, feeEGP is null and feeMinEGP/feeMaxEGP show the range. varies and source explain the result. Currency is EGP.

Next steps

  • Use integration-fee for a route-specific quote.

Usage

sh
akedly byo-sms fee

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms fee" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:read.

Server request: GET /byo-sms/fee.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Preview the account-level resolved BYO-SMS fee in EGP, including the account registry of active tested integrations; feeEGP is null when those integrations resolve to different fees; feeMinEGP and feeMaxEGP then give the range; this reads a price and does not charge or send. Also requires ana_rates_explorer:read. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are supported.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Explain account pricing; mixed fees yield null singular fee and min/max range.

sh
akedly byo-sms fee

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "feeEGP": 0.25,
    "feeMinEGP": 0.25,
    "feeMaxEGP": 0.25,
    "varies": false,
    "source": "default",
    "currency": "EGP"
  }
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms fee

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Schema describes the stable CLI-visible success envelope and known stable fields. API-owned fields may be added; fields omitted by member visibility or absent resource state may be absent.

Examples are synthetic; resource state, readiness, provider outcome, and fees vary by account.

Common error guidance.

byo-sms integration-fee

Quote one integration’s resolved fee; no send or charge.

When to use

  • Compare configured route cost.

How it works

  1. Server resolves integration/account/default fee chain.

Prerequisites

  • Owned integration and rate-read permission.

Expected outcome

feeEGP and EGP currency.

Next steps

  • Compare account-level quote as needed.

Usage

sh
akedly byo-sms integration-fee <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms integration-fee" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the id from akedly byo-sms list.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:read.

Server request: GET /byo-sms/integrations/:id/fee.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Preview the resolved feeEGP and currency EGP for one owned integration; this reads a price and does not charge or send. Also requires ana_rates_explorer:read. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are supported.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Compare configured route cost.

sh
akedly byo-sms integration-fee 64b000000000000000000001

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "feeEGP": 0.25,
    "currency": "EGP"
  }
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms integration-fee <id>

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Schema describes the stable CLI-visible success envelope and known stable fields. API-owned fields may be added; fields omitted by member visibility or absent resource state may be absent.

Examples are synthetic; resource state, readiness, provider outcome, and fees vary by account.

Common error guidance.

byo-sms egress-ips

Show Akedly outbound IP allowlist for this environment.

When to use

  • Give provider addresses during setup.

How it works

  1. Reads published, validated egress configuration only.

Prerequisites

  • Entitlement.

Expected outcome

Sorted addresses, environment and ready/missing/invalid state.

Next steps

  • Provider allowlisting is separate; ask support if missing/invalid.

Usage

sh
akedly byo-sms egress-ips

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms egress-ips" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:read.

Server request: GET /byo-sms/egress-ips.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Show the outbound IPv4 addresses Akedly sends BYO-SMS messages from in this environment. Give data.ips to your SMS provider so it can allow-list them. data.ips is a sorted list; data.environment and data.environmentLabel name the environment the list belongs to. data.status is ready, missing or invalid: missing means Akedly has not published addresses for this environment yet, and invalid means the published value was rejected; in both cases data.ips is empty, so ask Akedly support. data.verified is true only when the status is ready; it means Akedly accepted the published list, not that your provider has allow-listed it. This command sends nothing and changes nothing; it does not acknowledge or whitelist an address. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are supported.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Give provider addresses during setup.

sh
akedly byo-sms egress-ips

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "ips": [],
    "environment": "example",
    "environmentLabel": "EXAMPLE",
    "status": "missing",
    "verified": false
  }
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms egress-ips

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Schema describes the stable CLI-visible success envelope and known stable fields. API-owned fields may be added; fields omitted by member visibility or absent resource state may be absent.

Examples are synthetic; resource state, readiness, provider outcome, and fees vary by account.

Common error guidance.

byo-sms vodafone readiness

Review account/environment Vodafone pilot and operational blockers without sending.

When to use

  • Before Vodafone provisioning.

How it works

  1. Reads account-level setup readiness; test/activation eligibility remain false here. Per-integration eligibility is on get.

Prerequisites

  • Entitlement.

Expected outcome

Readiness and egress fingerprint.

Next steps

  • Resolve blockers with Akedly, then inspect Vodafone route readiness.

Usage

sh
akedly byo-sms vodafone readiness

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms vodafone readiness" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:read.

Server request: GET /byo-sms/vodafone/readiness.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read Vodafone environment, pilot, adapter, settlement and setup readiness without testing or sending. data.egress.fingerprint identifies the current environment and outbound-address configuration and is null until Akedly has verified those addresses; it is distinct from contractFingerprint. Readiness does not acknowledge or whitelist an address and does not enable sending. This account-level readiness always reports testEligible and activationEligible as false; for a Vodafone integration, byo-sms get shows its own vodafoneReadiness, including testEligible, activationEligible and whitelistAcknowledged; the stored acknowledgement timestamp and fingerprint are hidden. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are supported. Read blocker and deploymentBlocker for the reason codes and messages.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Before Vodafone provisioning.

sh
akedly byo-sms vodafone readiness

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "providerKey": "vodafone-elen",
    "adapterVersion": "1",
    "supportedCountries": [
      "EG"
    ],
    "credentials": "[REDACTED — synthetic secret omitted]",
    "sender": {
      "configured": false
    },
    "pilotEnabled": false,
    "pilotAccountAllowed": false,
    "pilotAccountIdsConfigured": false,
    "adapterAvailable": false,
    "quotaDebitLedgerReady": false,
    "contractFingerprint": null,
    "testContractFingerprint": null,
    "testContractMatches": false,
    "deploymentBlocker": {
      "code": "VODAFONE_PILOT_DISABLED",
      "message": "The Vodafone BYO-SMS pilot is not enabled yet."
    },
    "egress": {
      "environment": "example",
      "environmentLabel": "EXAMPLE",
      "ips": [],
      "status": "missing",
      "verified": false,
      "fingerprint": null
    },
    "externalActivationRequired": true,
    "testEligible": false,
    "activationEligible": false,
    "setupBlocker": null,
    "testBlocker": {
      "code": "VODAFONE_PILOT_DISABLED",
      "message": "The Vodafone BYO-SMS pilot is not enabled yet."
    },
    "activationBlocker": {
      "code": "VODAFONE_PILOT_DISABLED",
      "message": "The Vodafone BYO-SMS pilot is not enabled yet."
    },
    "blocker": {
      "code": "VODAFONE_PILOT_DISABLED",
      "message": "The Vodafone BYO-SMS pilot is not enabled yet."
    }
  }
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms vodafone readiness

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Schema describes the stable CLI-visible success envelope and known stable fields. API-owned fields may be added; fields omitted by member visibility or absent resource state may be absent.

Examples are synthetic; resource state, readiness, provider outcome, and fees vary by account.

Common error guidance.

byo-sms create

Create inactive account-level SMS route using generic provider steps or supported Vodafone managed configuration.

When to use

  • Connect a provider route before test and activation.

How it works

  1. Generic stores ordered HTTP steps, coverage, fail policy and secrets; Vodafone requires managed sender/credentials and its own provisioned setup. Creation can alert staff. Omitted --countries or ALL means catch-all coverage; the worked example passes EG and therefore shows Egypt-only coverage.

Prerequisites

  • Entitlement, granular pricing and routable countries; generic steps or Vodafone pilot/region approval.
  • Coverage is an intentional scope decision: omitted countries and a sole ALL value mean catch-all; include explicit country codes to restrict routing.

Expected outcome

Inactive sanitized integration; visible URL/templates may contain inline credentials.

Next steps

  • Review get, test with reviewed recipient and activate only on passing current configuration.

Usage

sh
akedly byo-sms create

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms create" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--nametext—yesCommand-specific option; see the full command details below. Manifest body field: name.
--descriptiontext—noCommand-specific option; see the full command details below. Manifest body field: description.
--on-failureenumstrict | fall-back-to-akedlynoCommand-specific option; see the full command details below. Manifest body field: onFailure. Tip: For OTP sends, fall-back-to-akedly is recommended: with it, if your provider fails, Akedly sends the SMS through its own providers at its normal SMS rates, not the flat Own SMS fee. With strict, the SMS fails and the pipeline's normal channel fallback continues. Utility SMS never uses the Akedly fallback, and on a managed Vodafone integration Akedly sets the failure behavior, so you cannot choose it.
--providerenumcustom-http | vodafone-elennoCommand-specific option; see the full command details below. Manifest body field: providerKey.
--sender-nametext—noCommand-specific option; see the full command details below. Manifest body field: providerConfig.senderName.
--countrieslist—noCommand-specific option; see the full command details below. Manifest body field: countries.
--steps-filetext—noCommand-specific option; see the full command details below. Manifest body field: steps. Tip: By default Akedly judges each step only by its HTTP status, so a provider error returned with an accepted status counts as success; add successAssertion jsonPathEquals or bodyMatches to the step to catch it, or prefer an endpoint that reports failure with an HTTP error status, and confirm real delivery when you test the integration.
--secrets-filetext—noCommand-specific option; see the full command details below. Manifest body field: secrets.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:create.

Server request: POST /byo-sms/integrations.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Sensitive output: echo-scrub. echo-scrub masks secret-shaped text, credential fields, secret query parameters and JSON secret fields inside strings in the response, such as a webhook receiver echo or BYO-SMS steps; keep the output private anyway.

Full command details

Create an inactive account-registry integration. --name is required; generic integrations need a non-empty JSON steps array (at most 1 MiB). --secrets-file is a JSON object (at most 64 KiB); never pass credentials in argv. Steps run in order. Step format: required url; method GET|POST|PUT|PATCH|DELETE (default POST); headers/query string maps (default {}); bodyType json|form|raw|none (default json); bodyTemplate (default empty string); auth with type none|bearer|basic|apiKeyHeader (default none), using token for bearer, username/password for basic or headerName/headerValue for apiKeyHeader. Optional successAssertion has statusIn (default [200,201,202]), jsonPathEquals {path,value} and bodyMatches regex; extract is an array of {name,from:status|header|jsonPath|regex,expr}. timeoutMs defaults to 3000; retryCount is 0-3 (default 0), only for the first step when it is not the send step; isSendStep defaults to false, and the first marked step or otherwise the last step is the send step. Templates support {{otp}}/{{message}}, {{otpMessage}}, {{phone}}, {{phoneLocal}}, {{secrets.<name>}} and {{vars.<name>}} from an earlier extract.name; for example {{secrets.apiKey}} reads the apiKey key from --secrets-file instead of embedding a literal credential. Secret and extraction names use letters, digits and underscore; a json bodyTemplate must form valid JSON after placeholder substitution. Countries are comma-separated; ALL alone means catch-all, omitted countries also mean catch-all; the server validates the routable catalog and rejects unknown or duplicate codes. onFailure defaults to fallbackToAkedly. Vodafone uses providerKey vodafone-elen, requires --sender-name and accountId/password/secureHashSecretKey in the secrets file, manages its own steps/onFailure and fixes countries to EG (omit those flags). Vodafone provisioning requires a supported region and the account to be allowed in the pilot; HTTP 403 names the blocker. Check akedly byo-sms vodafone readiness. Creation may notify Akedly staff. The server strips secrets and vodafoneSetup, but visible steps are returned verbatim and can contain literal credentials in auth, url or bodyTemplate; keep output private. --steps-file replaces the whole steps array, including headers and query: supply a complete file. Current get/list output serializes step headers/query as {}, so do not build a replacement steps file from that output or saved header/query values can be lost. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are refused.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Connect a provider route before test and activation.

sh
akedly byo-sms create --name 'Synthetic route' --countries EG --steps-file ./steps.json --secrets-file ./secrets.json

Input file: steps.json (json).

json
[
  {
    "url": "https://sms.example.invalid/send",
    "method": "POST",
    "headers": {},
    "query": {},
    "bodyType": "json",
    "bodyTemplate": "{\"to\":\"{{phone}}\",\"text\":\"{{otpMessage}}\",\"key\":\"{{secrets.apiKey}}\"}",
    "auth": {
      "type": "none"
    },
    "timeoutMs": 3000,
    "retryCount": 0,
    "isSendStep": true
  }
]

Input file: secrets.json (json).

json
{
  "apiKey": "[REDACTED — synthetic secret omitted]"
}

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000001",
    "userID": "64b000000000000000000010",
    "pipelineID": null,
    "name": "Synthetic route",
    "description": null,
    "uid": "11111111-1111-4111-8111-111111111111",
    "providerKey": "generic",
    "adapterVersion": null,
    "providerConfig": {
      "senderName": null
    },
    "countries": [
      "EG"
    ],
    "steps": [
      {
        "method": "POST",
        "url": "https://sms.example.invalid/send",
        "headers": {},
        "query": {},
        "bodyType": "json",
        "bodyTemplate": "{\"to\":\"{{phone}}\",\"text\":\"{{otpMessage}}\",\"key\":\"{{secrets.apiKey}}\"}",
        "auth": {
          "type": "none",
          "token": null,
          "username": null,
          "password": "[REDACTED — synthetic secret omitted]",
          "headerName": null,
          "headerValue": null
        },
        "timeoutMs": 3000,
        "retryCount": 0,
        "isSendStep": true,
        "successAssertion": {
          "statusIn": [
            200,
            201,
            202
          ],
          "jsonPathEquals": null,
          "bodyMatches": null
        },
        "extract": []
      }
    ],
    "onFailure": "fallbackToAkedly",
    "feeOverride": null,
    "active": false,
    "liveAnnouncedAt": null,
    "testPhone": null,
    "testStatus": {
      "passed": false,
      "lastTestedAt": null,
      "lastResultSummary": null,
      "providerSmsId": null,
      "certainty": null,
      "failureCategory": null,
      "lastTestKey": null,
      "contractFingerprint": null
    },
    "configHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "stepsVisible": true,
    "feeVisible": true,
    "secretNames": [
      "apiKey"
    ]
  }
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

The secrets file value SYNTHETIC-ONLY is a fake placeholder; never copy a real secret into chat or rendered docs.

This example explicitly passes --countries EG. If omitted, the backend stores an empty country list and treats it as catch-all; --countries ALL is also catch-all.

Create an inactive Egypt-only generic SMS route from complete JSON files

Register a generic HTTP SMS route with one send step and a separately stored API key. Explicit EG coverage prevents the omitted-country catch-all behavior. The route remains inactive until tested and deliberately activated.

sh
akedly byo-sms create --name 'Synthetic EG route' --countries EG --steps-file ./fixtures/eg-sms-steps.json --secrets-file ./fixtures/eg-sms-secrets.json

Input file: ./fixtures/eg-sms-steps.json (json).

json
[
  {
    "method": "POST",
    "url": "https://sms.example.invalid/send",
    "headers": {},
    "query": {},
    "bodyType": "json",
    "bodyTemplate": "{\"to\":\"{{phone}}\",\"text\":\"{{otpMessage}}\",\"api_key\":\"{{secrets.apiKey}}\"}",
    "auth": {
      "type": "none"
    },
    "timeoutMs": 3000,
    "retryCount": 0,
    "isSendStep": true,
    "successAssertion": {
      "statusIn": [
        200,
        201,
        202
      ]
    },
    "extract": []
  }
]

Input file: ./fixtures/eg-sms-secrets.json (json).

json
{
  "apiKey": "[REDACTED — synthetic secret omitted]"
}

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000001",
    "userID": "64b000000000000000000010",
    "pipelineID": null,
    "name": "Synthetic EG route",
    "description": null,
    "uid": "11111111-1111-4111-8111-111111111111",
    "providerKey": "generic",
    "adapterVersion": null,
    "providerConfig": {
      "senderName": null
    },
    "countries": [
      "EG"
    ],
    "steps": [
      {
        "method": "POST",
        "url": "https://sms.example.invalid/send",
        "headers": {},
        "query": {},
        "bodyType": "json",
        "bodyTemplate": "{\"to\":\"{{phone}}\",\"text\":\"{{otpMessage}}\",\"api_key\":\"{{secrets.apiKey}}\"}",
        "auth": {
          "type": "none",
          "token": null,
          "username": null,
          "password": "[REDACTED — synthetic secret omitted]",
          "headerName": null,
          "headerValue": null
        },
        "timeoutMs": 3000,
        "retryCount": 0,
        "isSendStep": true,
        "successAssertion": {
          "statusIn": [
            200,
            201,
            202
          ],
          "jsonPathEquals": null,
          "bodyMatches": null
        },
        "extract": []
      }
    ],
    "onFailure": "fallbackToAkedly",
    "feeOverride": null,
    "active": false,
    "liveAnnouncedAt": null,
    "testPhone": null,
    "testStatus": {
      "passed": false,
      "lastTestedAt": null,
      "lastResultSummary": null,
      "providerSmsId": null,
      "certainty": null,
      "failureCategory": null,
      "lastTestKey": null,
      "contractFingerprint": null
    },
    "configHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "stepsVisible": true,
    "feeVisible": true,
    "secretNames": [
      "apiKey"
    ]
  }
}

Synthetic-only endpoint uses the reserved .invalid domain. The fake key is illustrative and must never be used. The server response omits secret values and reports only secretNames. No provider request was made.

Additional command forms

sh
akedly byo-sms create --name <name> --steps-file <path>

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Schema describes the stable CLI-visible success envelope and known stable fields. API-owned fields may be added; fields omitted by member visibility or absent resource state may be absent.

Examples are synthetic; resource state, readiness, provider outcome, and fees vary by account.

Common error guidance.

byo-sms update

Change only named integration settings; endpoint/secret/coverage changes can invalidate test and deactivate route.

When to use

  • Maintain provider workflow or test destination.

How it works

  1. Partial write; steps file replaces complete chain; secrets merge, empty/null deletes; sensitive edits require --yes. Provider immutable.

Prerequisites

  • Owned integration; full intended steps including headers/query preserved.

Expected outcome

Updated route and readiness.

Next steps

  • Retest after invalidation; only activate passing current config.

Usage

sh
akedly byo-sms update <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms update" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the id from akedly byo-sms list.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--nametext—Command-specific option; see the full command details below. Manifest body field: name.
--descriptiontext—Command-specific option; see the full command details below. Manifest body field: description.
--on-failureenumstrict | fall-back-to-akedlyCommand-specific option; see the full command details below. Manifest body field: onFailure. Tip: For OTP sends, fall-back-to-akedly is recommended: with it, if your provider fails, Akedly sends the SMS through its own providers at its normal SMS rates, not the flat Own SMS fee. With strict, the SMS fails and the pipeline's normal channel fallback continues. Utility SMS never uses the Akedly fallback, and on a managed Vodafone integration Akedly sets the failure behavior, so you cannot choose it.
--providerenumcustom-http | vodafone-elenCommand-specific option; see the full command details below. Manifest body field: providerKey.
--sender-nametext—Command-specific option; see the full command details below. Manifest body field: providerConfig.senderName.
--countrieslist—Command-specific option; see the full command details below. Manifest body field: countries.
--steps-filetext—Command-specific option; see the full command details below. Manifest body field: steps. Tip: By default Akedly judges each step only by its HTTP status, so a provider error returned with an accepted status counts as success; add successAssertion jsonPathEquals or bodyMatches to the step to catch it, or prefer an endpoint that reports failure with an HTTP error status, and confirm real delivery when you test the integration.
--secrets-filetext—Command-specific option; see the full command details below. Manifest body field: secrets.
--test-phone-numbertext—Command-specific option; see the full command details below. Manifest body field: testPhone.
--yesboolean switch—Confirm this action where consent is required.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:update.

Server request: PUT /byo-sms/integrations/:id.

Shared server-guard guidance.

Consent

--yes when --steps-file or --secrets-file or --countries or --sender-name is given. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Sensitive output: echo-scrub. echo-scrub masks secret-shaped text, credential fields, secret query parameters and JSON secret fields inside strings in the response, such as a webhook receiver echo or BYO-SMS steps; keep the output private anyway.

Full command details

Update only supplied fields; supply at least one. See akedly byo-sms create --help for the generic steps-file format and secret placeholders. --steps-file, --secrets-file, --countries or --sender-name requires --yes because changed steps/coverage/secrets can deactivate the integration and invalidate its test; a Vodafone sender-name change deactivates an active integration, which then needs a new test. Secret keys merge with stored values; null or an empty string removes a generic secret, while omitted keys are preserved. Provider cannot be changed. --provider is accepted only when it equals the current provider. Vodafone sender/credential changes also deactivate and invalidate the test; Vodafone manages steps/onFailure/testPhone and EG coverage. --test-phone-number changes the saved generic test destination without invalidating the test; the server validates and normalizes international numbers. The server strips secrets and vodafoneSetup, but visible steps are returned verbatim and can contain literal credentials in auth, url or bodyTemplate; keep output private. --steps-file replaces the whole steps array, including headers and query: supply a complete file. Current get/list output serializes step headers/query as {}, so do not build a replacement steps file from that output or saved header/query values can be lost. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are refused.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Maintain provider workflow or test destination.

sh
akedly byo-sms update 64b000000000000000000001 --name 'Synthetic route v2'

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000001",
    "userID": "64b000000000000000000010",
    "pipelineID": null,
    "name": "Synthetic route v2",
    "description": null,
    "uid": "11111111-1111-4111-8111-111111111111",
    "providerKey": "generic",
    "adapterVersion": null,
    "providerConfig": {
      "senderName": null
    },
    "countries": [
      "EG"
    ],
    "steps": [
      {
        "method": "POST",
        "url": "https://sms.example.invalid/send",
        "headers": {},
        "query": {},
        "bodyType": "json",
        "bodyTemplate": "{\"to\":\"{{phone}}\",\"text\":\"{{otpMessage}}\",\"key\":\"{{secrets.apiKey}}\"}",
        "auth": {
          "type": "none",
          "token": null,
          "username": null,
          "password": "[REDACTED — synthetic secret omitted]",
          "headerName": null,
          "headerValue": null
        },
        "timeoutMs": 3000,
        "retryCount": 0,
        "isSendStep": true,
        "successAssertion": {
          "statusIn": [
            200,
            201,
            202
          ],
          "jsonPathEquals": null,
          "bodyMatches": null
        },
        "extract": []
      }
    ],
    "onFailure": "fallbackToAkedly",
    "feeOverride": null,
    "active": false,
    "liveAnnouncedAt": null,
    "testPhone": null,
    "testStatus": {
      "passed": false,
      "lastTestedAt": null,
      "lastResultSummary": null,
      "providerSmsId": null,
      "certainty": null,
      "failureCategory": null,
      "lastTestKey": null,
      "contractFingerprint": null
    },
    "configHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "stepsVisible": true,
    "feeVisible": true,
    "secretNames": [
      "apiKey"
    ]
  }
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Replace route steps and rotate its secret with confirmation

Replace the complete step chain and rotate apiKey on an existing generic route. Both file inputs are supplied because the steps file replaces the whole chain and the secrets file merges the named key. --yes is required for these configuration changes.

sh
akedly byo-sms update 64b000000000000000000001 --countries EG --steps-file ./fixtures/eg-sms-steps.json --secrets-file ./fixtures/eg-sms-secrets.json --yes

Input file: ./fixtures/eg-sms-steps.json (json).

json
[
  {
    "method": "POST",
    "url": "https://sms.example.invalid/send",
    "headers": {},
    "query": {},
    "bodyType": "json",
    "bodyTemplate": "{\"to\":\"{{phone}}\",\"text\":\"{{otpMessage}}\",\"api_key\":\"{{secrets.apiKey}}\"}",
    "auth": {
      "type": "none"
    },
    "timeoutMs": 3000,
    "retryCount": 0,
    "isSendStep": true,
    "successAssertion": {
      "statusIn": [
        200,
        201,
        202
      ]
    },
    "extract": []
  }
]

Input file: ./fixtures/eg-sms-secrets.json (json).

json
{
  "apiKey": "[REDACTED — synthetic secret omitted]"
}

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000001",
    "userID": "64b000000000000000000010",
    "pipelineID": null,
    "name": "Synthetic EG route",
    "description": null,
    "uid": "11111111-1111-4111-8111-111111111111",
    "providerKey": "generic",
    "adapterVersion": null,
    "providerConfig": {
      "senderName": null
    },
    "countries": [
      "EG"
    ],
    "steps": [
      {
        "method": "POST",
        "url": "https://sms.example.invalid/send",
        "headers": {},
        "query": {},
        "bodyType": "json",
        "bodyTemplate": "{\"to\":\"{{phone}}\",\"text\":\"{{otpMessage}}\",\"api_key\":\"{{secrets.apiKey}}\"}",
        "auth": {
          "type": "none",
          "token": null,
          "username": null,
          "password": "[REDACTED — synthetic secret omitted]",
          "headerName": null,
          "headerValue": null
        },
        "timeoutMs": 3000,
        "retryCount": 0,
        "isSendStep": true,
        "successAssertion": {
          "statusIn": [
            200,
            201,
            202
          ],
          "jsonPathEquals": null,
          "bodyMatches": null
        },
        "extract": []
      }
    ],
    "onFailure": "fallbackToAkedly",
    "feeOverride": null,
    "active": false,
    "liveAnnouncedAt": null,
    "testPhone": null,
    "testStatus": {
      "passed": false,
      "lastTestedAt": null,
      "lastResultSummary": null,
      "providerSmsId": null,
      "certainty": null,
      "failureCategory": null,
      "lastTestKey": null,
      "contractFingerprint": null
    },
    "configHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "stepsVisible": true,
    "feeVisible": true,
    "secretNames": [
      "apiKey"
    ]
  }
}

Synthetic existing integration ID, endpoint, and key; no provider request was made. The response omits secret values. --yes confirms a potentially deactivating configuration change; it does not test or activate the route.

Additional command forms

sh
akedly byo-sms update <id> --name <name>

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Schema describes the stable CLI-visible success envelope and known stable fields. API-owned fields may be added; fields omitted by member visibility or absent resource state may be absent.

Examples are synthetic; resource state, readiness, provider outcome, and fees vary by account.

Common error guidance.

byo-sms delete

Permanently remove route; its coverage can no longer send.

When to use

  • Retire route after checking dependencies.

How it works

  1. Deletes owned integration with --yes.

Prerequisites

  • Owned id and confirmation.

Expected outcome

Deletion message.

Next steps

  • Reevaluate remaining coverage and routing.

Usage

sh
akedly byo-sms delete <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms delete" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the id from akedly byo-sms list.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--yesboolean switch—Confirm this action where consent is required.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:delete.

Server request: DELETE /byo-sms/integrations/:id.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: true. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Permanently delete your integration. Requires --yes; sends using this integration can no longer route through it. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are refused.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Retire route after checking dependencies.

sh
akedly byo-sms delete 64b000000000000000000001 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "Integration deleted"
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms delete <id> --yes

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Schema describes the stable CLI-visible success envelope and known stable fields. API-owned fields may be added; fields omitted by member visibility or absent resource state may be absent.

Examples are synthetic; resource state, readiness, provider outcome, and fees vary by account.

Common error guidance.

byo-sms clone

Copy an integration and encrypted credentials/fee override to an owned non-system pipeline, inactive.

When to use

  • Isolate route settings per pipeline.

How it works

  1. Revalidates countries and Vodafone provisioning gates before copying.

Prerequisites

  • Source owned, pipeline owned/non-system, coverage routable; Vodafone pilot eligibility.

Expected outcome

New inactive pipeline integration.

Next steps

  • Test copy independently, then activate and set pipeline route policy.

Usage

sh
akedly byo-sms clone <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms clone" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the id from akedly byo-sms list.

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--pipeline-idid—yesCommand-specific option; see the full command details below. Manifest body field: pipelineID.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:create.

Server request: POST /byo-sms/integrations/:id/clone.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Sensitive output: echo-scrub. echo-scrub masks secret-shaped text, credential fields, secret query parameters and JSON secret fields inside strings in the response, such as a webhook receiver echo or BYO-SMS steps; keep the output private anyway.

Full command details

Copy an owned integration, including encrypted secrets and its fee override, onto an owned non-system pipeline. The copy is inactive and must pass its own test before activation. Vodafone provisioning requires a supported region and the account to be allowed in the pilot; HTTP 403 names the blocker. Check akedly byo-sms vodafone readiness. The source coverage is revalidated; SOURCE_COVERAGE_UNROUTABLE requires fixing the source before cloning. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are refused.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Isolate route settings per pipeline.

sh
akedly byo-sms clone 64b000000000000000000001 --pipeline-id 64b000000000000000000002

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000001",
    "userID": "64b000000000000000000010",
    "pipelineID": "64b000000000000000000002",
    "name": "Synthetic route",
    "description": null,
    "uid": "11111111-1111-4111-8111-111111111111",
    "providerKey": "generic",
    "adapterVersion": null,
    "providerConfig": {
      "senderName": null
    },
    "countries": [
      "EG"
    ],
    "steps": [
      {
        "method": "POST",
        "url": "https://sms.example.invalid/send",
        "headers": {},
        "query": {},
        "bodyType": "json",
        "bodyTemplate": "{\"to\":\"{{phone}}\",\"text\":\"{{otpMessage}}\",\"key\":\"{{secrets.apiKey}}\"}",
        "auth": {
          "type": "none",
          "token": null,
          "username": null,
          "password": "[REDACTED — synthetic secret omitted]",
          "headerName": null,
          "headerValue": null
        },
        "timeoutMs": 3000,
        "retryCount": 0,
        "isSendStep": true,
        "successAssertion": {
          "statusIn": [
            200,
            201,
            202
          ],
          "jsonPathEquals": null,
          "bodyMatches": null
        },
        "extract": []
      }
    ],
    "onFailure": "fallbackToAkedly",
    "feeOverride": null,
    "active": false,
    "liveAnnouncedAt": null,
    "testPhone": null,
    "testStatus": {
      "passed": false,
      "lastTestedAt": null,
      "lastResultSummary": null,
      "providerSmsId": null,
      "certainty": null,
      "failureCategory": null,
      "lastTestKey": null,
      "contractFingerprint": null
    },
    "configHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "stepsVisible": true,
    "feeVisible": true,
    "secretNames": [
      "apiKey"
    ]
  }
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms clone <id> --pipeline-id <id>

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Schema describes the stable CLI-visible success envelope and known stable fields. API-owned fields may be added; fields omitted by member visibility or absent resource state may be absent.

Examples are synthetic; resource state, readiness, provider outcome, and fees vary by account.

Common error guidance.

byo-sms test

Send one real activation test through saved provider chain; provider acceptance is not handset delivery.

When to use

  • Validate exact workflow and recipient before route activation.

How it works

  1. Generic: supplied/saved phone passed to placeholders, but saved steps decide actual recipient and may hardcode it; retries may send again. Vodafone uses managed handset and guarded operation recovery.

Prerequisites

  • Reviewed get/config/actual recipient, --yes, entitlement; Vodafone readiness.

Expected outcome

accepted and testedTo plus trace; 200 accepted:false means failed test, 202 may mean replay pending.

Next steps

  • Inspect get before retrying ambiguity; preserve same Vodafone key. Activation requires current passing test.

Usage

sh
akedly byo-sms test <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms test" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the id from akedly byo-sms list.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--yesboolean switch—Confirm this action where consent is required.
--test-phone-numbertext—Command-specific option; see the full command details below. Manifest body field: testPhone.
--idempotency-keytext—Command-specific option; see the full command details below. Manifest body field: idempotencyKey.
--allow-new-after-unknownboolean switch—Command-specific option; see the full command details below. Manifest body field: allowNewAfterUnknown.
--previous-test-keytext—Command-specific option; see the full command details below. Manifest body field: newAttempt.reason, newAttempt.previousTestKey.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:execute.

Server request: POST /byo-sms/integrations/:id/test.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: true.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Send a real activation-test message; requires --yes. Generic tests pass --test-phone-number, or else the saved destination, to the saved steps as {{phone}}/{{phoneLocal}}. The saved steps decide the real recipient; a step that hard-codes a number sends there. Check url and bodyTemplate with akedly byo-sms get <id>; step headers and query currently show as {}, so a number there is not visible. data.testedTo is the destination Akedly supplied, not proof of the real recipient. A generic test saves that supplied destination as its test number; a later bare test reuses the saved number. Vodafone ignores --test-phone-number and always uses Akedly's managed test handset. New Vodafone test attempts return HTTP 409 with a readiness blocker until vodafoneReadiness.testEligible. A UUID idempotencyKey is generated when omitted and retained in error details; reuse the same key after an ambiguous Vodafone result. Generic tests do not deduplicate by key and retrying can send again. --allow-new-after-unknown explicitly permits a new Vodafone attempt after an uncertain result; --previous-test-key explicitly requests another attempt after an accepted result. Keys are 1 to 255 characters. HTTP 200 with data.accepted:false is a failed test but exits 0; inspect data.accepted and data.testedTo. HTTP 202 is an in-progress replay. A pass can notify Akedly on Discord; failure deactivates the integration. Best-effort per-process hourly limits are 20/account and 10/recipient for generic tests, 10/account and 20/shared handset for Vodafone, and 60 duplicate replays/account. TEST_RATE_LIMITED returns HTTP 429 with Retry-After and cooldownSeconds; no automatic retry. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are refused.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Validate exact workflow and recipient before route activation.

sh
akedly byo-sms test 64b000000000000000000001 --test-phone-number +201234567890 --idempotency-key 11111111-1111-4111-8111-111111111111 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "accepted": true,
    "testedTo": "+201234567890",
    "trace": [
      {
        "step": 0,
        "attempt": 1,
        "method": "POST",
        "url": "https://sms.example.invalid/send",
        "requestHeaders": {
          "content-type": "application/json"
        },
        "requestBody": "{\"to\":\"+201234567890\",\"text\":\"[REDACTED]\",\"key\":\"[REDACTED]\"}",
        "status": 200,
        "responseBody": "{\"accepted\":true}",
        "ok": true
      }
    ],
    "failureReason": null,
    "failedStep": null,
    "certainty": "accepted",
    "failureCategory": null,
    "providerSmsId": "provider-message-synthetic",
    "providerAccepted": true,
    "providerKey": "generic",
    "submissionStatus": "accepted",
    "lastTestKey": null,
    "certificationBlocked": false,
    "passed": true,
    "billingPending": false,
    "billed": false,
    "transactionID": null,
    "operationId": null,
    "operationReplayable": false,
    "replayable": false,
    "guidance": null
  }
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms test <id> --yes

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Examples are synthetic; resource state, readiness, provider outcome, and fees vary by account.

Trace rows are the executor’s redacted/truncated HTTP request and response evidence; they may still include provider URLs and other operational data, so keep them private.

Generic and Vodafone test responses share accepted/testedTo/trace; Vodafone may add certainty, certification and operation-replay fields. HTTP 200 accepted:false is a completed failure; HTTP 202 carries inProgress.

Trace rows are redacted/truncated executor request and response evidence; URLs and operational metadata remain private.

Common error guidance.

byo-sms set-active

Activate/deactivate integration; active state can differ from effective routing.

When to use

  • Activate a tested conflict-free route or immediately stop one.

How it works

  1. Requires exactly one action; activation checks test/config, country overlap, and Vodafone eligibility; reports routingEnabled separately.

Prerequisites

  • Owned route; activation needs --yes and passing current test; Vodafone eligibility.

Expected outcome

Active state plus root routingEnabled and optional reason hint.

Next steps

  • Follow hint to account/pipeline BYO-SMS switch; recheck get/list.

Usage

sh
akedly byo-sms set-active <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms set-active" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the id from akedly byo-sms list.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--yesboolean switch—Confirm this action where consent is required.
--activateboolean switch—Command-specific option; see the full command details below. Manifest body field: active.
--deactivateboolean switch—Command-specific option; see the full command details below. Manifest body field: active.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:update.

Server request: POST /byo-sms/integrations/:id/activate.

Shared server-guard guidance.

Consent

--yes when --activate is given. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Pass exactly one of --activate or --deactivate. Activation needs --yes, a passing test for the current configuration and no country conflict in this scope; deactivation needs no --yes. On a country-conflict HTTP 409, run akedly byo-sms list and deactivate the active integration in the same pipelineID scope that covers overlapping countries; the CLI omits the server conflicts list. Vodafone activation also requires vodafoneReadiness.activationEligible; HTTP 409 names its readiness blocker. First activation can notify Akedly on Discord and WhatsApp. routingEnabled and routingHint are top-level response fields beside data. The response includes routingEnabled and possibly routingHint: active alone does not mean traffic routes through it; account/pipeline routing must also allow BYO-SMS. Change a pipeline's BYO-SMS setting with akedly pipelines update <id> --byo-sms inherit|on|off --yes; the account switch is set by Akedly. When active is true but routingEnabled is false, this integration is not taking production traffic; follow routingHint. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are refused.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

Activate a tested conflict-free route or immediately stop one.

sh
akedly byo-sms set-active 64b000000000000000000001 --activate --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000001",
    "userID": "64b000000000000000000010",
    "pipelineID": null,
    "name": "Synthetic route",
    "description": null,
    "uid": "11111111-1111-4111-8111-111111111111",
    "providerKey": "generic",
    "adapterVersion": null,
    "providerConfig": {
      "senderName": null
    },
    "countries": [
      "EG"
    ],
    "steps": [
      {
        "method": "POST",
        "url": "https://sms.example.invalid/send",
        "headers": {},
        "query": {},
        "bodyType": "json",
        "bodyTemplate": "{\"to\":\"{{phone}}\",\"text\":\"{{otpMessage}}\",\"key\":\"{{secrets.apiKey}}\"}",
        "auth": {
          "type": "none",
          "token": null,
          "username": null,
          "password": "[REDACTED — synthetic secret omitted]",
          "headerName": null,
          "headerValue": null
        },
        "timeoutMs": 3000,
        "retryCount": 0,
        "isSendStep": true,
        "successAssertion": {
          "statusIn": [
            200,
            201,
            202
          ],
          "jsonPathEquals": null,
          "bodyMatches": null
        },
        "extract": []
      }
    ],
    "onFailure": "fallbackToAkedly",
    "feeOverride": null,
    "active": true,
    "liveAnnouncedAt": null,
    "testPhone": null,
    "testStatus": {
      "passed": true,
      "lastTestedAt": "2026-01-01T00:00:00.000Z",
      "lastResultSummary": "passed",
      "providerSmsId": "synthetic-provider-id",
      "certainty": "accepted",
      "failureCategory": null,
      "lastTestKey": null,
      "contractFingerprint": null
    },
    "configHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "stepsVisible": true,
    "feeVisible": true,
    "secretNames": [
      "apiKey"
    ]
  },
  "routingEnabled": false,
  "routingHint": "Integration is active, but BYO-SMS routing is off for this account/pipeline."
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms set-active <id> --activate --yes

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Schema describes the stable CLI-visible success envelope and known stable fields. API-owned fields may be added; fields omitted by member visibility or absent resource state may be absent.

Examples are synthetic; resource state, readiness, provider outcome, and fees vary by account.

Common error guidance.

byo-sms vodafone acknowledge

Record customer acknowledgement that current Vodafone outbound addresses were allow-listed.

When to use

  • After provider-side IP allowlisting.

How it works

  1. Stores matching current egress fingerprint; stale fingerprint refused. This is not a send gate or activation.

Prerequisites

  • Vodafone integration, verified current fingerprint, completed allowlisting, --yes.

Expected outcome

whitelistAcknowledged true; timestamp/fingerprint hidden.

Next steps

  • Refresh readiness then separately test/activate when eligible.

Usage

sh
akedly byo-sms vodafone acknowledge <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "byo-sms vodafone acknowledge" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the id from akedly byo-sms list.

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--yesboolean switch—noConfirm this action where consent is required.
--fingerprinttext—yesCommand-specific option; see the full command details below. Manifest body field: egressFingerprint.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: byo_sms:update.

Server request: POST /byo-sms/integrations/:id/whitelist-acknowledgment.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Record that you have whitelisted the displayed Vodafone sending addresses; requires --fingerprint and --yes. Read data.egress.fingerprint from akedly byo-sms vodafone readiness or data.vodafoneReadiness.egress.fingerprint from akedly byo-sms get <id>. EGRESS_FINGERPRINT_STALE means refresh and check the address list before acknowledging again. This does not send, enable sending or act as a send gate. The saved state appears as vodafoneReadiness.whitelistAcknowledged; the stored acknowledgement timestamp and fingerprint are hidden. Only Vodafone integrations support it. Requires BYO-SMS entitlement and granular pricing; HTTP 403 (shown as PERMISSION_DENIED) can mean BYO-SMS is not enabled, not only a missing role permission; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and a role refusal names details.permission. Read-only logins are refused.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic request and response

After provider-side IP allowlisting.

sh
akedly byo-sms vodafone acknowledge 64b000000000000000000001 --fingerprint aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000001",
    "userID": "64b000000000000000000010",
    "pipelineID": null,
    "name": "Synthetic route",
    "description": null,
    "uid": "11111111-1111-4111-8111-111111111111",
    "providerKey": "vodafone-elen",
    "adapterVersion": "1",
    "providerConfig": {
      "senderName": "SYNTHETIC"
    },
    "countries": [
      "EG"
    ],
    "steps": [],
    "onFailure": "strict",
    "feeOverride": null,
    "active": false,
    "liveAnnouncedAt": null,
    "testPhone": null,
    "testStatus": {
      "passed": false,
      "lastTestedAt": null,
      "lastResultSummary": null,
      "providerSmsId": null,
      "certainty": null,
      "failureCategory": null,
      "lastTestKey": null,
      "contractFingerprint": null
    },
    "configHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "stepsVisible": true,
    "feeVisible": true,
    "secretNames": [
      "accountId",
      "password",
      "secureHashSecretKey"
    ],
    "vodafoneReadiness": {
      "providerKey": "vodafone-elen",
      "adapterVersion": "1",
      "supportedCountries": [
        "EG"
      ],
      "credentials": "[REDACTED — synthetic secret omitted]",
      "sender": {
        "configured": true
      },
      "pilotEnabled": false,
      "pilotAccountAllowed": false,
      "pilotAccountIdsConfigured": false,
      "adapterAvailable": false,
      "quotaDebitLedgerReady": false,
      "contractFingerprint": null,
      "testContractFingerprint": null,
      "testContractMatches": false,
      "deploymentBlocker": {
        "code": "VODAFONE_PILOT_DISABLED",
        "message": "The Vodafone BYO-SMS pilot is not enabled yet."
      },
      "egress": {
        "environment": "example",
        "environmentLabel": "EXAMPLE",
        "ips": [
          "8.8.8.8"
        ],
        "status": "ready",
        "verified": true,
        "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      "externalActivationRequired": true,
      "testEligible": false,
      "activationEligible": false,
      "setupBlocker": null,
      "testBlocker": {
        "code": "VODAFONE_PILOT_DISABLED",
        "message": "The Vodafone BYO-SMS pilot is not enabled yet."
      },
      "activationBlocker": {
        "code": "VODAFONE_PILOT_DISABLED",
        "message": "The Vodafone BYO-SMS pilot is not enabled yet."
      },
      "blocker": {
        "code": "VODAFONE_PILOT_DISABLED",
        "message": "The Vodafone BYO-SMS pilot is not enabled yet."
      },
      "whitelistAcknowledged": true
    }
  }
}

Example is documentation only and has not been run. Resource ids do not assert existing state.

Keep BYO-SMS output private: visible endpoint/template text may contain literal credentials.

Additional command forms

sh
akedly byo-sms vodafone acknowledge <id> --fingerprint <fingerprint> --yes

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Schema describes the stable CLI-visible success envelope and known stable fields. API-owned fields may be added; fields omitted by member visibility or absent resource state may be absent.

Examples are synthetic; resource state, readiness, provider outcome, and fees vary by account.

Common error guidance.