Utilities operations and sandbox
Akedly CLI command reference: Utilities operations and sandbox.
utilities sandbox status
check fixed sandbox readiness, account balance, rolling allowance and latest attempt before deciding whether to run a sandbox send.
When to use
- check fixed sandbox readiness, account balance, rolling allowance and latest attempt before deciding whether to run a sandbox send.
How it works
- The status service reports access and owner metadata, fixed template/preview, channel readiness with reason, EGP quote, balance, rolling allowance, and latest serialized attempt.
- A member sees restricted null states; an owner GET can provision the system-managed pipeline when prerequisites/indexes permit.
Prerequisites
- Authenticated account with utilities:read permission.
- Owner login for full status; a GET can provision the managed sandbox pipeline but sends nothing. Member view is restricted.
Expected outcome
A status snapshot with access, readiness reasons, costs, available balance, rolling allowance and latest attempt; nullable member values are expected.
Next steps
- If ready and authorized, use sandbox send; inspect latestAttempt by its Mongo id.
Usage
akedly utilities sandbox status
Inspect this command offline before preparing an operation:
akedly describe "utilities sandbox status" --output json
Flags
| Flag | Type | Enum / range | Description |
|---|---|---|---|
--ksa | boolean switch | — | Select the KSA deployment. |
--help | boolean switch | — | Show offline command help. |
--output | enum | json | human | Select JSON or human output. |
--fields | dot-paths | — | Select comma-separated safe dot paths; apply to each element of a root array. |
Authentication, permission and guards
Auth: login. Permission: utilities:read.
Server request: GET /utilities/sandbox/status.
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 the fixed Utilities sandbox status, current channel readiness and EGP quotes, available balance, rolling 60-minute allowance and data.latestAttempt. Read-only logins are supported. An owner session can provision the system-managed sandbox pipeline during this GET; it sends no utility message. A member session gets a restricted view. Sends use the saved owner phone, fixed content and Akedly sender, with eligible Egyptian SMS fallback. Current allowance is server-controlled; inspect data.allowance.remaining and data.allowance.nextAvailableAt rather than assuming a fixed quota. Use data.latestAttempt.id, a Mongo id, with akedly utilities sandbox attempt <id> to inspect an existing attempt.
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 CLI scenario
check fixed sandbox readiness, account balance, rolling allowance and latest attempt before deciding whether to run a sandbox send.
akedly utilities sandbox status
Illustrative response (sensitive values omitted):
{
"status": "success",
"data": {
"access": {
"allowed": true,
"reason": null
},
"owner": {
"phoneMasked": "+20 •• ••• •• 23",
"country": "EG",
"name": "Example Owner"
},
"template": {
"state": "approved",
"name": "akedly_utility_demo_order_v1",
"language": "en",
"checkedAt": "2050-01-02T03:04:05.000Z",
"detail": null
},
"preview": {
"header": "DEMO - no real order",
"body": "Hi {{name}}, this is a sample order notification from Akedly Utilities.",
"footer": "Sent from the Akedly Utilities sandbox",
"buttons": [
{
"type": "URL",
"text": "Explore Utilities"
}
],
"examples": {
"name": "there",
"reference": "DEMO-XXXXXX"
},
"smsText": "DEMO - no real order. Demo message. View: https://docs.akedly.io/utilities",
"language": "en",
"dir": "ltr"
},
"channels": {
"whatsapp": {
"available": true,
"reason": null
},
"sms": {
"available": true,
"reason": null
}
},
"quote": {
"currency": "EGP",
"whatsapp": {
"available": true,
"total": 0.75,
"reason": null
},
"sms": {
"available": true,
"total": 0.5,
"segments": 1,
"encoding": "GSM-7",
"reason": null
}
},
"balance": {
"available": 250,
"currency": "EGP",
"sufficient": true,
"required": 0.75
},
"allowance": {
"limit": 2,
"source": "global",
"remaining": 2,
"windowMinutes": 60,
"nextAvailableAt": null,
"disabled": false,
"globalDefault": 2
},
"latestAttempt": null
}
}
Resource identifiers and records are fictional prerequisites, not claims that these resources exist.
Additional command forms
akedly utilities sandbox status
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
Read the fixed Utilities sandbox status, current channel readiness and EGP quotes, available balance, rolling 60-minute allowance and data.latestAttempt. Read-only logins are supported. An owner session can provision the system-managed sandbox pipeline during this GET; it sends no utility message. A member session gets a restricted view. Sends use the saved owner phone, fixed content and Akedly sender, with eligible Egyptian SMS fallback. Current allowance is server-controlled; inspect data.allowance.remaining and data.allowance.nextAvailableAt rather than assuming a fixed quota. Use data.latestAttempt.id, a Mongo id, with akedly utilities sandbox attempt <id> to inspect an existing attempt.
Response fields outside the modeled stable fields may be passed through from the server.
The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.
Member sessions legitimately receive null owner, quote, balance, allowance and latestAttempt; check access.reason before using those fields.
The service can report no active owner phone, unapproved system template, unready WABA/pricing/index, insufficient balance, disabled allowance, or member-restricted nulls; inspect each explicit reason rather than deriving a single ready boolean.
utilities sandbox send
run Akedly’s fixed-content sandbox transaction to the saved owner phone; this is a real, chargeable send with no recipient/content override.
When to use
- run Akedly’s fixed-content sandbox transaction to the saved owner phone; this is a real, chargeable send with no recipient/content override.
How it works
- The server checks owner access, active/verified account and saved phone, fixed system-template readiness, channel pricing/sender readiness, balance and rolling allowance.
- The attempt response is serialized by the same attempt DTO used in status and attempt lookup; billed is a charge object {amount,currency} or null.
- Same-owner UUID-v4 key replay returns the stored attempt without resending; a new key starts a new separately billed operation.
Prerequisites
- Authenticated account with utilities:send permission.
- Writable owner account and explicit confirmation where required.
- Owner login, saved valid owner phone, active verified account, ready template/sender, sufficient available balance and remaining rolling allowance;
--yes. No recipient or content override exists.
Expected outcome
Returns attempt state; replay is HTTP 200 with replay:true and a new attempt is normally 201. Success is not handset delivery.
Next steps
- Inspect attempt by Mongo id and messages by transactionID. On uncertainty preserve key and inspect status/history; new key is a new billed operation.
Usage
akedly utilities sandbox send
Inspect this command offline before preparing an operation:
akedly describe "utilities sandbox send" --output json
Flags
| Flag | Type | Enum / range | Description |
|---|---|---|---|
--ksa | boolean switch | — | Select the KSA deployment. |
--idempotency-key | text | — | Command-specific option; see the full command details below. Manifest body field: idempotencyKey. |
--yes | boolean switch | — | Confirm this action where consent is required. |
--dry-run | boolean switch | — | Preview without sending the write or creating output files; planning reads may still occur. Bypass consent. |
--help | boolean switch | — | Show offline command help. |
--output | enum | json | human | Select JSON or human output. |
--fields | dot-paths | — | Select comma-separated safe dot paths; apply to each element of a root array. |
Authentication, permission and guards
Auth: login. Permission: utilities:send.
Server request: POST /utilities/sandbox/send.
Consent
--yes. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: true. 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, billed Utilities sandbox message to the saved owner phone with fixed content and Akedly's sender; eligible Egyptian failures can fall back to SMS. Requires an owner login, --yes, active/verified account, saved valid phone, sufficient available balance, current allowance and ready system template/sender. Read-only logins are refused; restricted impersonation is blocked. Recipient, content, template, pipeline and channel cannot be overridden. Only a UUID-v4 idempotencyKey is sent. Optional --idempotency-key is trimmed and lowercased; omission generates one key per plan, preserved in recovery error details. Save an explicit key for recovery. An existing same-owner key returns the saved attempt, including failed or uncertain attempts, and never resends it; a new key starts a new, separately billed operation. New attempts normally return 201; replay returns 200 with replay:true. HTTP success is not delivery: inspect data.attempt.phase, terminal, channel and billed. Run akedly utilities sandbox status for current readiness, balance, rolling 60-minute allowance and latestAttempt; after SANDBOX_RATE_LIMITED inspect data.allowance.nextAvailableAt. Use data.attempt.id or data.latestAttempt.id with akedly utilities sandbox attempt <id>; transactionID belongs to utilities messages get <transactionID>. Uses a 90-second request timeout with no automatic ambiguous retry. On timeout, inspect status/attempt and utilities messages list/get, retain the original key and do not create a new operation merely to escape uncertainty. --dry-run validates and prints the planned key/body without consent, credentials or a request. A rejected WhatsApp sandbox send still counts against the rolling allowance. The CLI does not retry a sandbox send after a timeout or server error; only a refusal coded CLI_RATE_LIMITED, which sends nothing, is retried.
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 CLI scenario
run Akedly’s fixed-content sandbox transaction to the saved owner phone; this is a real, chargeable send with no recipient/content override.
akedly utilities sandbox send --yes --idempotency-key 00000000-0000-4000-8000-000000000001
Illustrative response (sensitive values omitted):
{
"status": "success",
"data": {
"attempt": {
"id": "64b000000000000000000003",
"idempotencyKey": "00000000-0000-4000-8000-000000000001",
"reference": "DEMO-ABC123",
"createdAt": "2050-01-02T03:04:05.000Z",
"updatedAt": "2050-01-02T03:04:10.000Z",
"phase": "delivered",
"terminal": true,
"channel": "whatsapp",
"whatsapp": {
"status": "delivered",
"failureReason": null
},
"sms": null,
"billed": {
"amount": 0.75,
"currency": "EGP"
},
"transactionID": "txn_example_20500102",
"pollUntil": "2050-01-02T03:19:05.000Z",
"recipientMasked": "+20 •• ••• •• 23",
"countsTowardAllowance": true
}
},
"replay": false
}
Synthetic example only; do not execute against a live account.
Additional command forms
akedly utilities sandbox send --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
Send a REAL, billed Utilities sandbox message to the saved owner phone with fixed content and Akedly's sender; eligible Egyptian failures can fall back to SMS. Requires an owner login, --yes, active/verified account, saved valid phone, sufficient available balance, current allowance and ready system template/sender. Read-only logins are refused; restricted impersonation is blocked. Recipient, content, template, pipeline and channel cannot be overridden. Only a UUID-v4 idempotencyKey is sent. Optional --idempotency-key is trimmed and lowercased; omission generates one key per plan, preserved in recovery error details. Save an explicit key for recovery. An existing same-owner key returns the saved attempt, including failed or uncertain attempts, and never resends it; a new key starts a new, separately billed operation. New attempts normally return 201; replay returns 200 with replay:true. HTTP success is not delivery: inspect data.attempt.phase, terminal, channel and billed. Run akedly utilities sandbox status for current readiness, balance, rolling 60-minute allowance and latestAttempt; after SANDBOX_RATE_LIMITED inspect data.allowance.nextAvailableAt. Use data.attempt.id or data.latestAttempt.id with akedly utilities sandbox attempt <id>; transactionID belongs to utilities messages get <transactionID>. Uses a 90-second request timeout with no automatic ambiguous retry. On timeout, inspect status/attempt and utilities messages list/get, retain the original key and do not create a new operation merely to escape uncertainty. --dry-run validates and prints the planned key/body without consent, credentials or a request. A rejected WhatsApp sandbox send still counts against the rolling allowance. The CLI does not retry a sandbox send after a timeout or server error; only a refusal coded CLI_RATE_LIMITED, which sends nothing, is retried.
Response fields outside the modeled stable fields may be passed through from the server.
The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.
Own recovery guidance
| Code | Hint |
|---|---|
| SANDBOX_OWNER_ONLY | Run akedly login and approve it in the account owner's own dashboard session, then run akedly utilities sandbox status. |
| SANDBOX_IDEMPOTENCY_CONFLICT | Keep the original key for its original owner and operation. Run akedly utilities sandbox status and inspect the existing attempt before deciding on a different, separately billed operation. |
| SANDBOX_INDEX_UNAVAILABLE | Ask Akedly support to repair the sandbox purpose indexes, then run akedly utilities sandbox status. |
| SANDBOX_TEMPLATE_UNAVAILABLE | The fixed Akedly template or sender needs operator attention; ask Akedly support to check it, then run akedly utilities sandbox status and inspect data.template and data.channels. |
| SANDBOX_PHONE_MISSING | The saved account phone is missing or not a valid number. Customers cannot change it after sign-up: if it was never set, sign in to the dashboard and complete your profile; otherwise ask Akedly support to correct it. Then run akedly utilities sandbox status. This command cannot override the recipient. |
| RECIPIENT_SUPPRESSED | Run akedly utilities suppressions list and respect the saved owner phone opt-out. Resolve consent before any new send. |
| SANDBOX_DISABLED | Ask Akedly support to review the sandbox allowance setting, then run akedly utilities sandbox status and inspect data.allowance. |
| SANDBOX_PRICING_UNAVAILABLE | Ask Akedly support to check sandbox pricing, then run akedly utilities sandbox status and inspect data.quote before a new send. |
| INSUFFICIENT_BALANCE | Run akedly billing quota and fund the account through the dashboard, then run akedly utilities sandbox status. If data.latestAttempt carries your idempotencyKey and failed, that key only replays the failed attempt, so send with a new key; if no attempt was saved for your key, nothing was recorded and the same key can be used. |
| SANDBOX_RATE_LIMITED | Run akedly utilities sandbox status and inspect data.allowance.remaining and data.allowance.nextAvailableAt before a new operation. |
| DESTINATION_COUNTRY_BLOCKED | The saved owner phone is refused by the selected server region. Run akedly utilities sandbox status to inspect its masked destination; use the appropriate region or ask Akedly support without bypassing destination policy. |
| UTILITY_FEE_UNAVAILABLE | Nothing was sent by this attempt. Its key is already tied to a saved attempt. Run akedly utilities sandbox status, then akedly utilities sandbox attempt <id> to inspect its phase and billed state. The same key only replays the saved attempt, including a failed attempt; it never retries a failed attempt. Use a new key only after verifying that no message was sent and the budget issue is resolved; a new key is a new, separately billed operation. |
| UTILITY_BUDGET_RESERVATION_ID_MISSING | Nothing was sent by this attempt. Its key is already tied to a saved attempt. Run akedly utilities sandbox status, then akedly utilities sandbox attempt <id> to inspect its phase and billed state. The same key only replays the saved attempt, including a failed attempt; it never retries a failed attempt. Use a new key only after verifying that no message was sent and the budget issue is resolved; a new key is a new, separately billed operation. |
| UTILITY_BUDGET_RESERVATION_PENDING | Nothing was sent by this attempt. Its key is already tied to a saved attempt. Run akedly utilities sandbox status, then akedly utilities sandbox attempt <id> to inspect its phase and billed state. The same key only replays the saved attempt, including a failed attempt; it never retries a failed attempt. Use a new key only after verifying that no message was sent and the budget issue is resolved; a new key is a new, separately billed operation. |
| UTILITY_BUDGET_RECONCILIATION_PENDING | Nothing was sent by this attempt. Its key is already tied to a saved attempt. Run akedly utilities sandbox status, then akedly utilities sandbox attempt <id> to inspect its phase and billed state. The same key only replays the saved attempt, including a failed attempt; it never retries a failed attempt. Use a new key only after verifying that no message was sent and the budget issue is resolved; a new key is a new, separately billed operation. |
| UTILITY_BUDGET_RESERVATION_MISMATCH | Keep the original key and ask Akedly support to check the recorded fee; run akedly utilities sandbox status and inspect its latest attempt before a new operation. |
| SPEND_CAP_EXCEEDED | Ask Akedly support to review the system sandbox pipeline spend cap, then run akedly utilities sandbox status and inspect any saved attempt before a new send. |
utilities sandbox attempt
inspect one owned sandbox attempt without resending.
When to use
- inspect one owned sandbox attempt without resending.
How it works
- Fetch an attempt using Mongo id from status/send, not transactionID. Owner-only; member sessions are refused.
Prerequisites
- Authenticated account with utilities:read permission.
- Owner login and an attempt Mongo id from sandbox status/send; member sessions are refused.
Expected outcome
Returns attempt phase, terminal status, channel and billed status.
Next steps
- For transaction details use messages get with transactionID.
Usage
akedly utilities sandbox attempt <id>
Inspect this command offline before preparing an operation:
akedly describe "utilities sandbox attempt" --output json
| Positional | Grammar | Usage guidance |
|---|---|---|
| <id> | ^[a-fA-F0-9]{24}$ | Use data.attempt.id from akedly utilities sandbox send or data.latestAttempt.id from akedly utilities sandbox status. |
Flags
| Flag | Type | Enum / range | Description |
|---|---|---|---|
--ksa | boolean switch | — | Select the KSA deployment. |
--help | boolean switch | — | Show offline command help. |
--output | enum | json | human | Select JSON or human output. |
--fields | dot-paths | — | Select comma-separated safe dot paths; apply to each element of a root array. |
Authentication, permission and guards
Auth: login. Permission: utilities:read.
Server request: GET /utilities/sandbox/attempts/:id.
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 an existing owned sandbox attempt using the 24-hex Mongo id from data.attempt.id in sandbox send or data.latestAttempt.id in sandbox status, not transactionID. Requires an owner login; member sessions are refused. Read-only logins are supported for the owner. This observes state without resending. HTTP success can contain terminal failed or uncertain state: inspect data.attempt.phase, terminal, channel and billed. Use transactionID with akedly utilities messages get <transactionID> for message history.
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 CLI scenario
inspect one owned sandbox attempt without resending.
akedly utilities sandbox attempt 64b000000000000000000001
Illustrative response (sensitive values omitted):
{
"status": "success",
"data": {
"attempt": {
"id": "64b000000000000000000003",
"idempotencyKey": "00000000-0000-4000-8000-000000000001",
"reference": "DEMO-ABC123",
"createdAt": "2050-01-02T03:04:05.000Z",
"updatedAt": "2050-01-02T03:04:10.000Z",
"phase": "delivered",
"terminal": true,
"channel": "whatsapp",
"whatsapp": {
"status": "delivered",
"failureReason": null
},
"sms": null,
"billed": {
"amount": 0.75,
"currency": "EGP"
},
"transactionID": "txn_example_20500102",
"pollUntil": "2050-01-02T03:19:05.000Z",
"recipientMasked": "+20 •• ••• •• 23",
"countsTowardAllowance": true
}
}
}
Resource identifiers and records are fictional prerequisites, not claims that these resources exist.
Additional command forms
akedly utilities sandbox attempt <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
Read an existing owned sandbox attempt using the 24-hex Mongo id from data.attempt.id in sandbox send or data.latestAttempt.id in sandbox status, not transactionID. Requires an owner login; member sessions are refused. Read-only logins are supported for the owner. This observes state without resending. HTTP success can contain terminal failed or uncertain state: inspect data.attempt.phase, terminal, channel and billed. Use transactionID with akedly utilities messages get <transactionID> for message history.
Response fields outside the modeled stable fields may be passed through from the server.
The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.
The attempt DTO is shared with sandbox status.latestAttempt and sandbox send.data.attempt; billed is {amount,currency:"EGP"} or null, never a boolean.
Own recovery guidance
| Code | Hint |
|---|---|
| SANDBOX_OWNER_ONLY | Run akedly login and approve it in the account owner's own dashboard session, then run akedly utilities sandbox status. |
| SANDBOX_ATTEMPT_NOT_FOUND | Run akedly utilities sandbox status and use data.latestAttempt.id with akedly utilities sandbox attempt <id>; the id is the owned attempt Mongo id, not transactionID. |
utilities messages list
review utility-send outcomes to distinguish skipped, pending, provider failure and later delivery verdicts.
When to use
- review utility-send outcomes to distinguish skipped, pending, provider failure and later delivery verdicts.
How it works
- Filter owned transactions by known status/channel, exact phone and pipeline; paginate (offset pages are not snapshots).
Prerequisites
- Authenticated account with utilities:read permission.
Expected outcome
Returns transactions and pagination. Skipped means recipient was suppressed at request time; current suppressions are a separate list.
Next steps
- Open transactionID with messages get; use delivery events for asynchronous provider status.
Usage
akedly utilities messages list
Inspect this command offline before preparing an operation:
akedly describe "utilities messages list" --output json
Flags
| Flag | Type | Enum / range | Description |
|---|---|---|---|
--ksa | boolean switch | — | Select the KSA deployment. |
--status | enum | Pending | Successful | Failed | Skipped | Command-specific option; see the full command details below. Query parameter: status. |
--phone-number | text | — | Command-specific option; see the full command details below. Query parameter: phone. |
--pipeline-id | id | — | Command-specific option; see the full command details below. Query parameter: pipelineID. |
--channel | text | — | Command-specific option; see the full command details below. Query parameter: channel. |
--page | integer | 1 to unbounded | Command-specific option; see the full command details below. Query parameter: page. |
--limit | integer | 1 to 100 | Command-specific option; see the full command details below. Query parameter: limit. |
--all | boolean switch | — | Command-specific option; see the full command details below. |
--help | boolean switch | — | Show offline command help. |
--output | enum | json | human | Select JSON or human output. |
--fields | dot-paths | — | Select comma-separated safe dot paths; apply to each element of a root array. |
Authentication, permission and guards
Auth: login. Permission: utilities:read.
Server request: GET /utilities/messages.
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 your utility sends, including Skipped outcomes. --status accepts Pending, Successful, Failed or Skipped; unknown values are refused locally because the server ignores them. Failed and Successful filters incorporate later provider delivery verdicts. --phone-number is an exact canonical phone-number match, not a substring search; --pipeline-id is a 24-hex id. Page defaults to 1 and limit to 20; --all defaults omitted limit to 100 and uses the shared Pagination rules. Offset paging is not a snapshot and can skip rows during concurrent changes. Provider submission acceptance does not prove handset delivery. Read-only logins are supported. Skipped means the recipient was suppressed when the send was requested; akedly utilities suppressions list shows current suppressions only. Known --channel values are whatsapp and sms.
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 CLI scenario
review utility-send outcomes to distinguish skipped, pending, provider failure and later delivery verdicts.
akedly utilities messages list
Illustrative response (sensitive values omitted):
{
"status": "success",
"message": "Utility messages fetched successfully",
"data": {
"messages": [
{
"_id": "64b000000000000000000003",
"transactionID": "txn_example_20500102",
"recipient": "+201234567890",
"status": "Successful",
"channel": "whatsapp",
"provider": "meta-cloud",
"providerKey": null,
"templateName": "Order update",
"segments": null,
"encoding": null,
"cost": null,
"deliveryStatus": "delivered",
"deliveredAt": "2050-01-02T03:04:20.000Z",
"submissionStatus": null,
"providerSmsId": null,
"submittedAt": null,
"submissionFailureReason": null,
"acknowledgedAt": null,
"pipeline": {
"_id": "64b000000000000000000001",
"name": "Example utility pipeline"
},
"creationDate": "2050-01-02T03:04:05.000Z"
}
],
"pagination": {
"currentPage": 1,
"totalPages": 1,
"totalCount": 1,
"limit": 20,
"hasNextPage": false,
"hasPreviousPage": false
}
}
}
Resource identifiers and records are fictional prerequisites, not claims that these resources exist.
Additional command forms
akedly utilities messages 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
List your utility sends, including Skipped outcomes. --status accepts Pending, Successful, Failed or Skipped; unknown values are refused locally because the server ignores them. Failed and Successful filters incorporate later provider delivery verdicts. --phone-number is an exact canonical phone-number match, not a substring search; --pipeline-id is a 24-hex id. Page defaults to 1 and limit to 20; --all defaults omitted limit to 100 and uses the shared Pagination rules. Offset paging is not a snapshot and can skip rows during concurrent changes. Provider submission acceptance does not prove handset delivery. Read-only logins are supported. Skipped means the recipient was suppressed when the send was requested; akedly utilities suppressions list shows current suppressions only. Known --channel values are whatsapp and sms.
Response fields outside the modeled stable fields may be passed through from the server.
The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.
utilities messages get
inspect the lifecycle and billing/delivery fields for one utility transaction.
When to use
- inspect the lifecycle and billing/delivery fields for one utility transaction.
How it works
- Fetch by transactionID from messages list; this is not Mongo _id.
Prerequisites
- Authenticated account with utilities:read permission.
Expected outcome
Returns one transaction record.
Next steps
- For later event context inspect messaging-events list; use acknowledge only when the recipient confirms receipt.
Usage
akedly utilities messages get <transactionID>
Inspect this command offline before preparing an operation:
akedly describe "utilities messages get" --output json
| Positional | Grammar | Usage guidance |
|---|---|---|
| <transactionID> | ^(?!\.\.?$)[\s\S]*\S | Use the transactionID from akedly utilities messages list. |
Flags
| Flag | Type | Enum / range | Description |
|---|---|---|---|
--ksa | boolean switch | — | Select the KSA deployment. |
--help | boolean switch | — | Show offline command help. |
--output | enum | json | human | Select JSON or human output. |
--fields | dot-paths | — | Select comma-separated safe dot paths; apply to each element of a root array. |
Authentication, permission and guards
Auth: login. Permission: utilities:read.
Server request: GET /utilities/messages/:transactionID.
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 one owned utility send using transactionID from akedly utilities messages list. This is a transaction identifier, not a Mongo id. It is sent exactly as given; blank values, `.` and `..` are refused locally. Submission acceptance, delivery and billing are separate outcomes. Read-only logins are supported.
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 CLI scenario
inspect the lifecycle and billing/delivery fields for one utility transaction.
akedly utilities messages get txn_example_20500102
Illustrative response (sensitive values omitted):
{
"status": "success",
"data": {
"transactionID": "txn_example_20500102",
"recipient": "+201234567890",
"status": "Pending",
"channel": "whatsapp",
"provider": "meta-cloud",
"providerKey": null,
"templateName": "Order update",
"segments": null,
"encoding": null,
"acknowledgedAt": null,
"delivery": null,
"submission": null,
"deliveryAttempts": 0,
"creationDate": "2050-01-02T03:04:05.000Z",
"pipeline": {
"_id": "64b000000000000000000001",
"name": "Example utility pipeline"
},
"bills": [],
"cost": null
}
}
Resource identifiers and records are fictional prerequisites, not claims that these resources exist.
Additional command forms
akedly utilities messages get <transactionID>
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
Read one owned utility send using transactionID from akedly utilities messages list. This is a transaction identifier, not a Mongo id. It is sent exactly as given; blank values, `.` and `..` are refused locally. Submission acceptance, delivery and billing are separate outcomes. Read-only logins are supported.
Response fields outside the modeled stable fields may be passed through from the server.
The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.
There is no billed flag on this DTO. `cost:null` means no completed bill is present; inspect `submission` (provider acceptance) and `delivery` (provider delivery verdict) separately.
utilities messaging-events list
investigate delivery status, inbound-message and button-action events for utility messaging.
When to use
- investigate delivery status, inbound-message and button-action events for utility messaging.
How it works
- Page the event feed, optionally by event/status/pipeline/date range; dates use server timezone and only latest 100 pages are reachable.
Prerequisites
- Authenticated account with utilities:read permission.
Expected outcome
Returns events and pagination; event text and phone numbers remain visible.
Next steps
- Match event transactionId to messages get; inbound rows may have null transactionId.
Usage
akedly utilities messaging-events list
Inspect this command offline before preparing an operation:
akedly describe "utilities messaging-events list" --output json
Flags
| Flag | Type | Enum / range | Description |
|---|---|---|---|
--ksa | boolean switch | — | Select the KSA deployment. |
--event-type | enum | message.status | message.inbound | button.action | Command-specific option; see the full command details below. Query parameter: eventType. |
--status | enum | sent | delivered | read | failed | Command-specific option; see the full command details below. Query parameter: status. |
--pipeline-id | id | — | Command-specific option; see the full command details below. Query parameter: pipelineId. |
--start-date | text | — | Command-specific option; see the full command details below. Query parameter: from. |
--end-date | text | — | Command-specific option; see the full command details below. Query parameter: to. |
--page | integer | 1 to 100 | Command-specific option; see the full command details below. Query parameter: page. |
--limit | integer | 1 to 100 | Command-specific option; see the full command details below. Query parameter: limit. |
--help | boolean switch | — | Show offline command help. |
--output | enum | json | human | Select JSON or human output. |
--fields | dot-paths | — | Select comma-separated safe dot paths; apply to each element of a root array. |
Authentication, permission and guards
Auth: login. Permission: utilities:read.
Server request: GET /utilities/messaging-events.
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 your utility delivery-status, inbound-message and button-action events. --pipeline-id is a 24-hex id. --start-date and --end-date are valid YYYY-MM-DD days; --end-date includes the entire end day in the server timezone. Page defaults to 1 and limit to 20 (maximum 100). This is a page-only feed with no --all. Only the newest 100 pages are reachable; use --start-date/--end-date to reach older events. Offset paging is not a snapshot and can skip rows during concurrent changes. Event text and phone numbers remain visible. Read-only logins are supported. Each row's transactionId is the transactionID used by akedly utilities messages get; inbound messages with no known origin have null. The server cannot filter by transactionId; narrow with --pipeline-id and --start-date/--end-date, then match rows.
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 CLI scenario
investigate delivery status, inbound-message and button-action events for utility messaging.
akedly utilities messaging-events list --start-date 2050-01-01 --end-date 2050-01-02
Illustrative response (sensitive values omitted):
{
"status": "success",
"data": {
"events": [
{
"_id": "64b000000000000000000004",
"transactionId": "txn_example_20500102",
"pipelineID": "64b000000000000000000001",
"templateId": "64b000000000000000000002",
"channel": "whatsapp",
"phoneNumber": "+201234567890",
"eventType": "message.status",
"status": "delivered",
"failureCode": null,
"failureReason": null,
"messageBody": null,
"buttonId": null,
"buttonLabel": null,
"receivedAt": "2050-01-02T03:04:20.000Z",
"createdAt": "2050-01-02T03:04:20.000Z"
}
],
"pagination": {
"currentPage": 1,
"totalPages": 1,
"totalCount": 1,
"limit": 20
}
}
}
Resource identifiers and records are fictional prerequisites, not claims that these resources exist.
Additional command forms
akedly utilities messaging-events 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
List your utility delivery-status, inbound-message and button-action events. --pipeline-id is a 24-hex id. --start-date and --end-date are valid YYYY-MM-DD days; --end-date includes the entire end day in the server timezone. Page defaults to 1 and limit to 20 (maximum 100). This is a page-only feed with no --all. Only the newest 100 pages are reachable; use --start-date/--end-date to reach older events. Offset paging is not a snapshot and can skip rows during concurrent changes. Event text and phone numbers remain visible. Read-only logins are supported. Each row's transactionId is the transactionID used by akedly utilities messages get; inbound messages with no known origin have null. The server cannot filter by transactionId; narrow with --pipeline-id and --start-date/--end-date, then match rows.
Response fields outside the modeled stable fields may be passed through from the server.
The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.
utilities pipelines webhook-deliveries
diagnose callback delivery history for an owned utility pipeline without retrying callbacks.
When to use
- diagnose callback delivery history for an owned utility pipeline without retrying callbacks.
How it works
- Fetch newest delivery pages for pipeline id; only latest 100 pages are reachable.
Prerequisites
- Authenticated account with utilities:read permission.
Expected outcome
Returns delivery attempts and pagination; eventId identifies event in callback body and is not transactionID.
Next steps
- Inspect callback endpoint health and pipeline webhook configuration; this command itself never retries.
Usage
akedly utilities pipelines webhook-deliveries <id>
Inspect this command offline before preparing an operation:
akedly describe "utilities pipelines webhook-deliveries" --output json
| Positional | Grammar | Usage guidance |
|---|---|---|
| <id> | ^[a-fA-F0-9]{24}$ | Use the id of an owned utility pipeline from akedly pipelines list. |
Flags
| Flag | Type | Enum / range | Description |
|---|---|---|---|
--ksa | boolean switch | — | Select the KSA deployment. |
--page | integer | 1 to 100 | Command-specific option; see the full command details below. Query parameter: page. |
--limit | integer | 1 to 100 | Command-specific option; see the full command details below. Query parameter: limit. |
--help | boolean switch | — | Show offline command help. |
--output | enum | json | human | Select JSON or human output. |
--fields | dot-paths | — | Select comma-separated safe dot paths; apply to each element of a root array. |
Authentication, permission and guards
Auth: login. Permission: utilities:read.
Server request: GET /utilities/pipelines/:id/webhook-deliveries.
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 webhook delivery history for an owned utility pipeline using its 24-hex id. This observes existing deliveries and does not retry callbacks. Page defaults to 1 and limit to 20 (maximum 100). This is a page-only feed with no --all. Only the newest 100 pages of deliveries are reachable. Offset paging is not a snapshot and can skip rows during concurrent changes. Read-only logins are supported. eventId is the eventId inside the webhook body sent to your callback; deliveries carry no transactionID.
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 CLI scenario
diagnose callback delivery history for an owned utility pipeline without retrying callbacks.
akedly utilities pipelines webhook-deliveries 64b000000000000000000001
Illustrative response (sensitive values omitted):
{
"status": "success",
"data": {
"deliveries": [
{
"_id": "64b000000000000000000006",
"eventId": "evt_example_20500102",
"eventType": "utility.message.created",
"status": "delivered",
"attempts": 1,
"lastStatusCode": 200,
"lastError": null,
"createdAt": "2050-01-02T03:04:05.000Z"
}
],
"pagination": {
"currentPage": 1,
"totalPages": 1,
"totalCount": 1,
"limit": 20
}
}
}
Resource identifiers and records are fictional prerequisites, not claims that these resources exist.
Additional command forms
akedly utilities pipelines webhook-deliveries <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
Read webhook delivery history for an owned utility pipeline using its 24-hex id. This observes existing deliveries and does not retry callbacks. Page defaults to 1 and limit to 20 (maximum 100). This is a page-only feed with no --all. Only the newest 100 pages of deliveries are reachable. Offset paging is not a snapshot and can skip rows during concurrent changes. Read-only logins are supported. eventId is the eventId inside the webhook body sent to your callback; deliveries carry no transactionID.
Response fields outside the modeled stable fields may be passed through from the server.
The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.
Delivery records expose `attempts` (plural), `lastStatusCode`, `lastError`, and `eventType`; page metadata is currentPage/totalPages/totalCount/limit.
utilities suppressions list
see current phone/channel blocks that apply across all utility pipelines, including owner sandbox.
When to use
- see current phone/channel blocks that apply across all utility pipelines, including owner sandbox.
How it works
- List suppression rows with pagination; ALL and individual channel records are independent.
Prerequisites
- Authenticated account with utilities:read permission.
Expected outcome
Returns current suppression rows and pagination, not the complete audit history.
Next steps
- Add a block immediately when requested; remove only with recipient consent, and clear the exact row.
Usage
akedly utilities suppressions list
Inspect this command offline before preparing an operation:
akedly describe "utilities suppressions list" --output json
Flags
| Flag | Type | Enum / range | Description |
|---|---|---|---|
--ksa | boolean switch | — | Select the KSA deployment. |
--page | integer | 1 to unbounded | Command-specific option; see the full command details below. Query parameter: page. |
--limit | integer | 1 to 100 | Command-specific option; see the full command details below. Query parameter: limit. |
--all | boolean switch | — | Command-specific option; see the full command details below. |
--help | boolean switch | — | Show offline command help. |
--output | enum | json | human | Select JSON or human output. |
--fields | dot-paths | — | Select comma-separated safe dot paths; apply to each element of a root array. |
Authentication, permission and guards
Auth: login. Permission: utilities:read.
Server request: GET /utilities/suppressions.
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 your currently suppressed phone/channel rows. ALL blocks either channel; an ALL row and an individual sms or whatsapp row remain separate suppression records. Page defaults to 1 and limit to 20; --all defaults omitted limit to 100 and uses the shared Pagination rules. Offset paging is not a snapshot and can skip rows during concurrent changes. Read-only logins are supported. Suppressions apply across this account's utility pipelines, including the owner sandbox. Use akedly utilities suppressions remove only with the recipient's consent.
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 CLI scenario
see current phone/channel blocks that apply across all utility pipelines, including owner sandbox.
akedly utilities suppressions list
Illustrative response (sensitive values omitted):
{
"status": "success",
"data": {
"suppressions": [
{
"_id": "64b000000000000000000005",
"phoneNumber": "+201234567890",
"channel": "whatsapp",
"source": "dashboard",
"lastEventAt": "2050-01-02T03:04:05.000Z"
}
],
"pagination": {
"currentPage": 1,
"totalPages": 1,
"totalCount": 1,
"limit": 20
}
}
}
Resource identifiers and records are fictional prerequisites, not claims that these resources exist.
Additional command forms
akedly utilities suppressions 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
List your currently suppressed phone/channel rows. ALL blocks either channel; an ALL row and an individual sms or whatsapp row remain separate suppression records. Page defaults to 1 and limit to 20; --all defaults omitted limit to 100 and uses the shared Pagination rules. Offset paging is not a snapshot and can skip rows during concurrent changes. Read-only logins are supported. Suppressions apply across this account's utility pipelines, including the owner sandbox. Use akedly utilities suppressions remove only with the recipient's consent.
Response fields outside the modeled stable fields may be passed through from the server.
The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.
Rows expose source and lastEventAt; this is current suppression state, not full audit history.
utilities messages acknowledge
record a recipient-confirmed acknowledgement for one delivered utility message.
When to use
- record a recipient-confirmed acknowledgement for one delivered utility message.
How it works
- POST acknowledgement by transactionID; first timestamp is preserved on repeats and operation is irreversible. Requires a writable login.
Prerequisites
- Authenticated account with utilities:update permission.
- Writable account login and evidence the recipient confirmed receipt of the utility message.
Expected outcome
Returns ok, acknowledgedAt and alreadyAcked; currently sends no webhook.
Next steps
- Verify timestamp through messages get; acknowledgement affects analytics.
Usage
akedly utilities messages acknowledge <transactionID>
Inspect this command offline before preparing an operation:
akedly describe "utilities messages acknowledge" --output json
| Positional | Grammar | Usage guidance |
|---|---|---|
| <transactionID> | ^(?!\.\.?$)[\s\S]*\S | Use the transactionID from akedly utilities messages list. |
Flags
| Flag | Type | Enum / range | Description |
|---|---|---|---|
--ksa | boolean switch | — | Select the KSA deployment. |
--dry-run | boolean switch | — | Preview without sending the write or creating output files; planning reads may still occur. Bypass consent. |
--help | boolean switch | — | Show offline command help. |
--output | enum | json | human | Select JSON or human output. |
--fields | dot-paths | — | Select comma-separated safe dot paths; apply to each element of a root array. |
Authentication, permission and guards
Auth: login. Permission: utilities:update.
Server request: POST /utilities/messages/:transactionID/acknowledge.
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
Acknowledge one owned utility message using its transactionID, not a Mongo id. Blank values, `.` and `..` are refused locally. The first acknowledgement timestamp is kept on repeats. The response data contains ok, acknowledgedAt and alreadyAcked. It records that the recipient acknowledged (confirmed receipt of) the message; it cannot be undone and delivered acknowledged sends count toward the Utilities analytics acknowledgement rate. It currently triggers no webhook. Check acknowledgedAt with akedly utilities messages get <transactionID>. Read-only logins are refused. --dry-run prints the validated request without contacting the server.
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 CLI scenario
record a recipient-confirmed acknowledgement for one delivered utility message.
akedly utilities messages acknowledge txn_example_20500102
Illustrative response (sensitive values omitted):
{
"status": "success",
"data": {
"ok": true,
"acknowledgedAt": "2050-01-02T03:04:05.000Z",
"alreadyAcked": false
}
}
Resource identifiers and records are fictional prerequisites, not claims that these resources exist.
Additional command forms
akedly utilities messages acknowledge <transactionID>
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
Acknowledge one owned utility message using its transactionID, not a Mongo id. Blank values, `.` and `..` are refused locally. The first acknowledgement timestamp is kept on repeats. The response data contains ok, acknowledgedAt and alreadyAcked. It records that the recipient acknowledged (confirmed receipt of) the message; it cannot be undone and delivered acknowledged sends count toward the Utilities analytics acknowledgement rate. It currently triggers no webhook. Check acknowledgedAt with akedly utilities messages get <transactionID>. Read-only logins are refused. --dry-run prints the validated request without contacting the server.
Response fields outside the modeled stable fields may be passed through from the server.
The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.
utilities suppressions add
immediately prevent future utility sends to a phone on all or one channel, without contacting that phone.
When to use
- immediately prevent future utility sends to a phone on all or one channel, without contacting that phone.
How it works
- Submit phone and channel; server canonicalizes phone. Each repeat appends audit history, so inspect list after ambiguous failure.
Prerequisites
- Authenticated account with utilities:update permission.
Expected outcome
Returns suppression result. ALL blocks both channels; separate channel rows remain independent.
Next steps
- Verify exact row with suppressions list; only remove after recipient consent.
Usage
akedly utilities suppressions add
Inspect this command offline before preparing an operation:
akedly describe "utilities suppressions add" --output json
Flags
| Flag | Type | Enum / range | Required | Description |
|---|---|---|---|---|
--ksa | boolean switch | — | no | Select the KSA deployment. |
--phone-number | text | — | yes | Command-specific option; see the full command details below. Manifest body field: phone. |
--channel | enum | all | sms | whatsapp | no | Command-specific option; see the full command details below. Manifest body field: channel. |
--dry-run | boolean switch | — | no | Preview without sending the write or creating output files; planning reads may still occur. Bypass consent. |
--help | boolean switch | — | no | Show offline command help. |
--output | enum | json | human | no | Select JSON or human output. |
--fields | dot-paths | — | no | Select comma-separated safe dot paths; apply to each element of a root array. |
Authentication, permission and guards
Auth: login. Permission: utilities:update.
Server request: POST /utilities/suppressions.
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
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
Suppress a recipient for future sends immediately without sending a message. Required --phone-number passes unchanged for server canonicalization. --channel defaults to all, which blocks both channels and is listed as ALL; separate sms and whatsapp rows are independent. Every repeat appends an audit event; an ambiguous network or server failure is not retried; run akedly utilities suppressions list before repeating. Read-only logins are refused. --dry-run prints the validated request without contacting the server. Suppressions apply across this account's utility pipelines, including the owner sandbox. Use akedly utilities suppressions remove only with the recipient's consent.
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 CLI scenario
immediately prevent future utility sends to a phone on all or one channel, without contacting that phone.
akedly utilities suppressions add --phone-number +201234567890 --channel whatsapp
Illustrative response (sensitive values omitted):
{
"status": "success",
"data": {
"ok": true,
"phone": "+201234567890",
"channel": "whatsapp"
}
}
Resource identifiers and records are fictional prerequisites, not claims that these resources exist.
Additional command forms
akedly utilities suppressions add --phone-number <number>
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
Suppress a recipient for future sends immediately without sending a message. Required --phone-number passes unchanged for server canonicalization. --channel defaults to all, which blocks both channels and is listed as ALL; separate sms and whatsapp rows are independent. Every repeat appends an audit event; an ambiguous network or server failure is not retried; run akedly utilities suppressions list before repeating. Read-only logins are refused. --dry-run prints the validated request without contacting the server. Suppressions apply across this account's utility pipelines, including the owner sandbox. Use akedly utilities suppressions remove only with the recipient's consent.
Response fields outside the modeled stable fields may be passed through from the server.
The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.
Own recovery guidance
| Code | Hint |
|---|---|
| MISSING_PHONE | Pass --phone-number with the recipient number. |
| INVALID_CHANNEL | Choose --channel all, sms or whatsapp (lower case). |
| INVALID_PHONE | Pass --phone-number with a valid E.164 number; the server canonicalizes it. |
utilities suppressions remove
restore future eligibility for exactly one suppression row after the recipient consents; it sends nothing.
When to use
- restore future eligibility for exactly one suppression row after the recipient consents; it sends nothing.
How it works
- Opt in the exact phone/channel row with confirmation; ALL and per-channel records must be removed separately.
Prerequisites
- Authenticated account with utilities:update permission.
- Writable owner account and explicit confirmation where required.
- Writable account login and recipient consent to opt in for exactly the selected channel row.
Expected outcome
Returns opt-in result and preserves history; repeated requests append audit events.
Next steps
- Verify with suppressions list before considering future sends.
Usage
akedly utilities suppressions remove
Inspect this command offline before preparing an operation:
akedly describe "utilities suppressions remove" --output json
Flags
| Flag | Type | Enum / range | Required | Description |
|---|---|---|---|---|
--ksa | boolean switch | — | no | Select the KSA deployment. |
--phone-number | text | — | yes | Command-specific option; see the full command details below. Manifest body field: phone. |
--channel | enum | all | sms | whatsapp | no | Command-specific option; see the full command details below. Manifest body field: channel. |
--yes | boolean switch | — | no | Confirm this action where consent is required. |
--dry-run | boolean switch | — | no | Preview without sending the write or creating output files; planning reads may still occur. Bypass consent. |
--help | boolean switch | — | no | Show offline command help. |
--output | enum | json | human | no | Select JSON or human output. |
--fields | dot-paths | — | no | Select comma-separated safe dot paths; apply to each element of a root array. |
Authentication, permission and guards
Auth: login. Permission: utilities:update.
Server request: POST /utilities/suppressions/opt-in.
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
Opt a recipient back in for exactly one channel row; requires --yes. Required --phone-number passes unchanged for server canonicalization. --channel defaults to all, the row listed as ALL. Opting in sms does not clear a suppressed ALL row; opting in all does not clear separate sms or whatsapp rows. History is kept, every repeat appends an audit event and an ambiguous network or server failure is not retried; run akedly utilities suppressions list before repeating. This changes future eligibility without sending a message. Read-only logins are refused. --dry-run prints the validated request without contacting the server. Suppressions apply across this account's utility pipelines, including the owner sandbox. Use akedly utilities suppressions remove only with the recipient's consent.
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 CLI scenario
restore future eligibility for exactly one suppression row after the recipient consents; it sends nothing.
akedly utilities suppressions remove --phone-number +201234567890 --channel whatsapp --yes
Illustrative response (sensitive values omitted):
{
"status": "success",
"data": {
"ok": true,
"phone": "+201234567890",
"channel": "whatsapp"
}
}
Resource identifiers and records are fictional prerequisites, not claims that these resources exist.
Additional command forms
akedly utilities suppressions remove --phone-number <number> --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
Opt a recipient back in for exactly one channel row; requires --yes. Required --phone-number passes unchanged for server canonicalization. --channel defaults to all, the row listed as ALL. Opting in sms does not clear a suppressed ALL row; opting in all does not clear separate sms or whatsapp rows. History is kept, every repeat appends an audit event and an ambiguous network or server failure is not retried; run akedly utilities suppressions list before repeating. This changes future eligibility without sending a message. Read-only logins are refused. --dry-run prints the validated request without contacting the server. Suppressions apply across this account's utility pipelines, including the owner sandbox. Use akedly utilities suppressions remove only with the recipient's consent.
Response fields outside the modeled stable fields may be passed through from the server.
The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.
Own recovery guidance
| Code | Hint |
|---|---|
| MISSING_PHONE | Pass --phone-number with the recipient number. |
| INVALID_CHANNEL | Choose --channel all, sms or whatsapp (lower case). |
| INVALID_PHONE | Pass --phone-number with a valid E.164 number; the server canonicalizes it. |