{
  "info": {
    "name": "SMSFabric API",
    "description": "The SMSFabric API with an API key: send a message, read its timeline, then verify, contacts, templates, campaigns and webhooks. Set `apiKey` to a key from the API keys page of the web app (a test key sends through the sandbox).",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "apikey",
    "apikey": [
      {
        "key": "key",
        "value": "X-Api-Key",
        "type": "string"
      },
      {
        "key": "value",
        "value": "{{apiKey}}",
        "type": "string"
      },
      {
        "key": "in",
        "value": "header",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.smsfabric.com",
      "type": "string"
    },
    {
      "key": "apiKey",
      "value": "",
      "type": "string",
      "description": "Your API key. Never save a real key in a shared collection."
    },
    {
      "key": "messageId",
      "value": "",
      "type": "string",
      "description": "A message id (msg_…). Postman fills it in after \"Send a message\"."
    },
    {
      "key": "poolId",
      "value": "",
      "type": "string",
      "description": "A pool id. Postman fills it in after \"Create a pool\"."
    },
    {
      "key": "scheduledAt",
      "value": "",
      "type": "string",
      "description": "ISO 8601 UTC time for \"Schedule a message\". Postman sets it to one hour from now before the request; in Insomnia, set it yourself."
    },
    {
      "key": "verificationId",
      "value": "",
      "type": "string",
      "description": "A verification id (ver_…). Postman fills it in after \"Send a code\"."
    },
    {
      "key": "templateId",
      "value": "",
      "type": "string",
      "description": "A template id. Postman fills it in after \"Create a template\"."
    },
    {
      "key": "campaignId",
      "value": "",
      "type": "string",
      "description": "A campaign id. Postman fills it in after \"Create a campaign\"."
    },
    {
      "key": "webhookId",
      "value": "",
      "type": "string",
      "description": "A webhook id (whk_…). Postman fills it in after \"Create a webhook\"."
    }
  ],
  "item": [
    {
      "name": "Messages",
      "item": [
        {
          "name": "Send a message",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if (pm.response.code >= 200 && pm.response.code < 300) {",
                  "  pm.collectionVariables.set(\"messageId\", pm.response.json().data[0].id);",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Idempotency-Key",
                "value": "{{$guid}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"to\": \"+201001234567\",\n  \"body\": \"Your order is out for delivery.\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/messages",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "messages"
              ]
            },
            "description": "Sends one SMS through your default SIM. Answers 201 with the message in `data[0]`, status `queued`. Needs the `messages:send` scope. `to` also takes up to 100 numbers."
          },
          "response": []
        },
        {
          "name": "Send through a pool",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if (pm.response.code >= 200 && pm.response.code < 300) {",
                  "  pm.collectionVariables.set(\"messageId\", pm.response.json().data[0].id);",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Idempotency-Key",
                "value": "{{$guid}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"to\": \"+201001234567\",\n  \"body\": \"Your order is out for delivery.\",\n  \"poolId\": \"{{poolId}}\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/messages",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "messages"
              ]
            },
            "description": "Routes round-robin over the online phones in the pool. If a phone drops, another phone in the pool takes the message. Run \"Create a pool\" first and put at least one phone in it."
          },
          "response": []
        },
        {
          "name": "Schedule a message",
          "event": [
            {
              "listen": "prerequest",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.variables.set(\"scheduledAt\", new Date(Date.now() + 60 * 60 * 1000).toISOString());"
                ]
              }
            },
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if (pm.response.code >= 200 && pm.response.code < 300) {",
                  "  pm.collectionVariables.set(\"messageId\", pm.response.json().data[0].id);",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Idempotency-Key",
                "value": "{{$guid}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"to\": \"+201001234567\",\n  \"body\": \"Your order is out for delivery.\",\n  \"scheduledAt\": \"{{scheduledAt}}\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/messages",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "messages"
              ]
            },
            "description": "Sends at `scheduledAt` (ISO 8601, UTC). Answers 403 `feature_not_in_plan` when the plan has no scheduled sends."
          },
          "response": []
        },
        {
          "name": "Get a message with its timeline",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/messages/{{messageId}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "messages",
                "{{messageId}}"
              ]
            },
            "description": "The message plus `events[]`: every step from queued to delivered or failed, with times."
          },
          "response": []
        },
        {
          "name": "List messages",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/messages?direction=outbound&limit=20",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "messages"
              ],
              "query": [
                {
                  "key": "direction",
                  "value": "outbound"
                },
                {
                  "key": "limit",
                  "value": "20"
                }
              ]
            },
            "description": "A page of messages. Filters: `direction`, `status`, `deviceId`, `campaignId`, `q` (phone), `from`, `to`. Pass `nextCursor` back as `cursor` for the next page."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Devices",
      "item": [
        {
          "name": "List devices",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/devices",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "devices"
              ]
            },
            "description": "Your paired phones with `status`, `battery`, `signal`, `lastSeenAt` and `sims[]`."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Pools",
      "item": [
        {
          "name": "Create a pool",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if (pm.response.code >= 200 && pm.response.code < 300) {",
                  "  pm.collectionVariables.set(\"poolId\", pm.response.json().id);",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Cairo\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/pools",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "pools"
              ]
            },
            "description": "A pool is a group of phones that take over for each other. Needs the `devices:manage` scope. Add a phone with `PATCH /v1/devices/:id { poolId }`. Answers 409 `pool_exists` for a name already in use."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Verify",
      "item": [
        {
          "name": "Send a code",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if (pm.response.code >= 200 && pm.response.code < 300) {",
                  "  pm.collectionVariables.set(\"verificationId\", pm.response.json().id);",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Idempotency-Key",
                "value": "{{$guid}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"to\": \"+201001234567\",\n  \"channel\": \"sms\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/verifications",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "verifications"
              ]
            },
            "description": "Texts a 6-digit code that expires in 10 minutes. The code is never in the response: only the recipient sees it. Needs the `verify:send` scope. Optional: `locale` (`en` or `ar`), `codeLength`, `ttlSeconds`, `template`."
          },
          "response": []
        },
        {
          "name": "Check a code",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"code\": \"123456\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/verifications/{{verificationId}}/check",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "verifications",
                "{{verificationId}}",
                "check"
              ]
            },
            "description": "Replace `code` with the digits the phone received. `approved` means it matched; `pending` comes with `attemptsLeft`; the 5th wrong code is `denied`. Needs the `verify:check` scope."
          },
          "response": []
        },
        {
          "name": "Get a verification",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/verifications/{{verificationId}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "verifications",
                "{{verificationId}}"
              ]
            },
            "description": "Status, attempts and expiry. `to` is masked to the calling code and the last 4 digits."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Contacts",
      "item": [
        {
          "name": "Create a contact",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Idempotency-Key",
                "value": "{{$guid}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phone\": \"+201001234567\",\n  \"firstName\": \"Mona\",\n  \"lastName\": \"Hassan\",\n  \"tags\": [\n    \"vip\"\n  ],\n  \"consent\": {\n    \"source\": \"api\"\n  }\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/contacts",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "contacts"
              ]
            },
            "description": "One contact per number. Answers 409 `contact_exists` for a number you already have. Needs the `contacts:manage` scope."
          },
          "response": []
        },
        {
          "name": "List contacts",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/contacts?tag=vip&limit=20",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "contacts"
              ],
              "query": [
                {
                  "key": "tag",
                  "value": "vip"
                },
                {
                  "key": "limit",
                  "value": "20"
                }
              ]
            },
            "description": "Newest first. Filters: `q` (number, last 4 digits, name or email), `tag`, `groupId`, `optedOut`."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Templates",
      "item": [
        {
          "name": "Create a template",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if (pm.response.code >= 200 && pm.response.code < 300) {",
                  "  pm.collectionVariables.set(\"templateId\", pm.response.json().id);",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Out for delivery\",\n  \"body\": \"Hi {{first_name|there}}, your order is out for delivery.\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/templates",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "templates"
              ]
            },
            "description": "Variables are `{{first_name}}`, `{{last_name}}` and `{{custom.<key>}}`, each with an optional fallback after `|`. Needs the `campaigns:manage` scope. Answers 409 `template_exists` for a name already in use."
          },
          "response": []
        },
        {
          "name": "Preview a template",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"body\": \"Hi {{first_name|there}}, your order is out for delivery.\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/templates/preview",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "templates",
                "preview"
              ]
            },
            "description": "Renders the text for a sample contact (or add `contactId` for a real one) and counts segments. Problems come back in `issues`, never as a 400."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Campaigns",
      "item": [
        {
          "name": "Create a campaign",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if (pm.response.code >= 200 && pm.response.code < 300) {",
                  "  pm.collectionVariables.set(\"campaignId\", pm.response.json().id);",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Delivery notice\",\n  \"tags\": [\n    \"vip\"\n  ],\n  \"templateId\": \"{{templateId}}\",\n  \"ratePerMinute\": 60\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/campaigns",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "campaigns"
              ]
            },
            "description": "Creates a draft for every contact tagged `vip`. Nothing is sent until `POST /v1/campaigns/:id/start`. Needs the `campaigns:manage` scope."
          },
          "response": []
        },
        {
          "name": "Estimate a campaign",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/campaigns/{{campaignId}}/estimate",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "campaigns",
                "{{campaignId}}",
                "estimate"
              ]
            },
            "description": "Recipients, exclusions, segments and how long the send takes on your phones. Sends nothing."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Webhooks",
      "item": [
        {
          "name": "Create a webhook",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if (pm.response.code >= 200 && pm.response.code < 300) {",
                  "  pm.collectionVariables.set(\"webhookId\", pm.response.json().id);",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"url\": \"https://example.com/hooks/smsfabric\",\n  \"events\": [\n    \"message.delivered\",\n    \"message.failed\",\n    \"message.received\"\n  ]\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/webhooks",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "webhooks"
              ]
            },
            "description": "Replace `url` with your HTTPS endpoint. The response includes `signingSecret` once: store it to verify the `SMSFabric-Signature` header. Needs the `webhooks:manage` scope."
          },
          "response": []
        },
        {
          "name": "Send a test event",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/webhooks/{{webhookId}}/test",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "webhooks",
                "{{webhookId}}",
                "test"
              ]
            },
            "description": "Sends a `webhook.test` event to the endpoint, signed like any other."
          },
          "response": []
        },
        {
          "name": "List deliveries",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/webhooks/{{webhookId}}/deliveries",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "webhooks",
                "{{webhookId}}",
                "deliveries"
              ]
            },
            "description": "Each attempt to reach your endpoint. A delivery that fails is tried up to 8 times over about 24 hours."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Blacklist",
      "item": [
        {
          "name": "Block a number",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phone\": \"+201009876543\",\n  \"reason\": \"Asked not to be contacted\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/blacklist",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "blacklist"
              ]
            },
            "description": "Sends to this number come back with status `blocked`. Needs the `blacklist:manage` scope."
          },
          "response": []
        },
        {
          "name": "List blocked numbers",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/blacklist",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "blacklist"
              ]
            },
            "description": "`source` is `manual`, or `opt_out` when the recipient replied STOP."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Plan",
      "item": [
        {
          "name": "Get your plan and usage",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/org/plan",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "org",
                "plan"
              ]
            },
            "description": "Limits, features and what you have used today and this month, with `dayResetsAt` and `monthResetsAt`."
          },
          "response": []
        }
      ]
    }
  ]
}
