Verify your integration

MyComm has no separate sandbox. You verify an integration against the real API with a dedicated test account, a dry run that sends nothing, and a webhook test. This page is the recipe, in the order to do it.

1. Use a dedicated test account#

Create one test account with its own API key, its own webhook secret and numbers you control. Never develop against a production account or a real recipient. Keep test and production secrets in separate places.

2. Prove the key#

GET /v1/account needs no ability. A 200 shows which account the key acts on, so you can see that a deployment is using the key you think it is using.

curl -sS "$MYCOMM_URL/v1/account" -H "Authorization: Bearer $MYCOMM_API_KEY"

3. Run a dry run#

Send the request you would send, with "dry_run": true.

curl -sS -X POST "$MYCOMM_URL/v1/messages" \
  -H "Authorization: Bearer $MYCOMM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+923001234567",
    "body": "Validation only",
    "category": "transactional",
    "dry_run": true
  }'

A dry run runs the same checks as a real send, in the same order, and then stops:

It stores, queues and sends nothing, and it does not use up the Idempotency-Key or the reference_id. The answer is 200 with the message it would create: dry_run: true, id, status and timestamps null, and the computed encoding, segments, type, hold_reason and expires_at. The hold_reason predicts compliance and scheduling holds only; a phone that is offline at send time shows up when the message really goes out.

A refusal is the same error a real send would give, so a settings screen can show it as it is:

{
  "error": {
    "code": "DESTINATION_NOT_ALLOWED",
    "message": "This channel may not send to that destination. Pick a recipient in an allowed country, or change the channel's allowed destinations.",
    "details": {"country": "GB", "allowed": ["PK"]},
    "request_id": "0198f3a2-7c41-7e0b-9d52-6a1f3b8c4e11",
    "doc_url": "https://mycomm.cogneer.tech/docs/errors#destination-not-allowed"
  }
}

A "test settings" button#

Run a dry run to a number you own when someone saves their MyComm settings, and show error.message if it fails. In PHP:

$response = $http->post("$base/v1/messages", [
    'headers' => ['Authorization' => "Bearer $key"],
    'json' => ['to' => $testNumber, 'body' => 'Settings check', 'category' => 'transactional', 'dry_run' => true],
    'http_errors' => false,
]);

$ok = $response->getStatusCode() === 200;
$problem = $ok ? null : json_decode((string) $response->getBody(), true)['error']['message'];

The PHP SDK, the Laravel package and the Node.js SDK have a verify() call that does this and more.

4. Send one real message to your own number#

Send without dry_run to a number you control and watch GET /v1/messages/{id} (or the message.* events) go through queued, sent and delivered. This is the first point where the phone and the carrier are involved.

5. Test your webhook endpoint#

Use the endpoint's test action (POST /v1/webhook-endpoints/{id}/test, or the button in the portal) to send a ping to your URL. Save a raw request with its MyComm-Signature header while you develop, then:

• replay a saved delivery to check that your handler is idempotent (the event id is the same on every retry);
• return a 5xx once on purpose and check that you recover when the retry arrives;
• check both message.received and the status events (message.sent, message.delivered, message.failed).

Replay a stored delivery with POST /v1/webhook-deliveries/{id}/replay. The event catalogue has a sample payload for every event.

Go-live checklist#

• The production account and key are separate from the test ones.
• The key holds only the abilities it needs, is limited to the lines it uses, and lives in a secret manager.
• Webhook delivery works over HTTPS and your handler checks the signature against the raw body.
• Handlers store the event id before processing and are safe to run twice.
• Every message job has an Idempotency-Key, and you record the answer.
• Opt-out, suppression and consent behaviour is what you want for your audience.
• The channel and phone are ready before the first send: online, not paused, within limits.
• Someone owns the alerts for queued, failed and held messages.
• Test recipients, test keys and temporary tunnels are gone.