{"openapi":"3.1.0","info":{"title":"Nuuday SMS Gateway","version":"2026.05.04-1138"},"paths":{"/v1/sms/submit":{"post":{"summary":"Submit Short Message","description":"Accept and submits a single SMS into the SMSC queues.\n\nThis API is asynchronous, therfore acceptance of an SMS does not mean that\nit has been delivered to the device, in fact, it does not even mean that it\nis possible to deliver the message, as some time consuming checks and\nvalidation steps has been deferred until later in the chain of delivery.\n\nUnder normal circumstances, all accepted messages will generate one or more\nDelivery Reports that will be processed like webhook events and sent back\nto the system that submitted the message.","operationId":"submit_short_message_v1_sms_submit_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShortMessageSubmit"},"examples":{"minimal":{"summary":"A minimal example","value":{"encoding":"gsm7","text":"Hello World!","sender":"ExampleSMS","recipient":"+4512345678"}},"unicode":{"summary":"Unicode support","description":"To support a wider character set than `GSM7`, use `UCS2`.","value":{"encoding":"ucs2","text":"Unicode Rocks! 🤘","sender":"ExampleSMS","recipient":"+4512345678"}},"expiration":{"summary":"Message expiration","description":"Instead of the somewhat rarely encountered ISO-8601 duration format, `expiration`can also be parsed from a offset in seconds, and even as a unix timestamp in seconds, or the more common `YYYY-MM-DD[T]HH:MM:SS[.ffffff][Z or [+ or -]HH[:]MM]` format.","value":{"encoding":"gsm7","text":"Hello World!","sender":"ExampleSMS","recipient":"+4512345678","expiration":"P2DT3H4M5S"}},"binary":{"summary":"Binary message","value":{"encoding":"binary","text":"48656C6C6F20576F726C6421","sender":"ExampleSMS","recipient":"+4512345678"}},"pre-split":{"summary":"Already split message","description":"By setting the correct header it is possible to send messages that was already split up and join them back together on the receiving device.\n\nNote that the SMSC is itself capable of splitting long messages into shorter ones and send them correctly.","value":{"encoding":"gsm7","text":"Part 1 of 3","sender":"ExampleSMS","recipient":"+4512345678","header":"050003440301"}}}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShortMessageResponse"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"token":[]}]}},"/v1/sms/log-dlr":{"get":{"summary":"Delivery Report Log","description":"Return a list of all received status reports.\n\nThis API should only be used for customers unable to get status reports\ndelivered to their webhook. Status reports available through this API are\nlimited to 7 days back in time.\n\nThe results are paginated, and the value in the `next` field should be used\nin the following API call to get all status reports received after that\ntimestamp.","operationId":"delivery_report_log_v1_sms_log_dlr_get","security":[{"token":[]}],"parameters":[{"name":"next","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Starting point in time for returning status reports. Defaults to 7 days in the past.\nAccepts the format:\n- `YYYY-MM-DDTHH:MM:SS[.ffffff][+ or -]HH:MM`.\n","title":"Next"},"description":"Starting point in time for returning status reports. Defaults to 7 days in the past.\nAccepts the format:\n- `YYYY-MM-DDTHH:MM:SS[.ffffff][+ or -]HH:MM`.\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDlrResponse"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too Many Requests"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sms/log-mo":{"get":{"summary":"Mobile Origin Message Log","description":"Return a list of all receiced Mobile Originated Messages.\n\nThis API should only be used for customers unlable to get messages\ndelivered to their webhook. Status reports available through this API are\nlimited to 7 days back in time.\n\nThe results are paginated, and the value of the `next` field should be used\nin the following API call to get all status reports received after that\ntimestamp.","operationId":"mobile_origin_message_log_v1_sms_log_mo_get","security":[{"token":[]}],"parameters":[{"name":"next","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Starting point in time for returning mobile origin messages.Defaults to 7 days in the past.\nAccepts the format:\n- `YYYY-MM-DDTHH:MM:SS[.ffffff][+ or -]HH:MM`.\n","title":"Next"},"description":"Starting point in time for returning mobile origin messages.Defaults to 7 days in the past.\nAccepts the format:\n- `YYYY-MM-DDTHH:MM:SS[.ffffff][+ or -]HH:MM`.\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogMOResponse"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too Many Requests"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"webhooks":{"receive-delivery-report":{"post":{"summary":"Receive Delivery Report","description":"Receive a delivery report from a submitted message.\n\nThe responding server _must_ respond with a status code in the successful\nrange between `200` and `299`, in order to mark the event as delivered.\n\nAny other responses will we treated as a failure to deliver and will cause\nthe event to be retried again later.","operationId":"receive_delivery_reportreceive_delivery_report_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryReport"},"examples":{"minimal":{"summary":"A minimal example","value":{"id":"01GA3CSYKJAB5QW8AMHQNJMT9D","recipient":4512345678,"reference":"","status":"delivered","status_at":"2022-08-10T08:12:35.901468+00:00"}},"reference":{"summary":"With reference","value":{"id":"01GA3CSYKJAB5QW8AMHQNJMT9D","recipient":4512345678,"reference":"this-was-included-at-submission","status":"delivered","status_at":"2022-08-10T08:12:35.901468+00:00"}},"sender-filtered":{"summary":"Sender Filtered","value":{"id":"01GA3CSYKJAB5QW8AMHQNJMT9D","recipient":4512345678,"reference":"","status":"rejected","status_at":"2022-08-10T08:12:35.901468+00:00","error":"sender_blocked"}},"sms-expired":{"summary":"SMS expired","description":"The `error` for expired SMS can either be generic or a specificname, depending on the system that produced the error.","value":{"id":"01GA3CSYKJAB5QW8AMHQNJMT9D","recipient":4512345678,"reference":"","status":"expired","status_at":"2022-08-10T08:12:35.901468+00:00","error":"expired"}},"unmapped-error":{"summary":"Generic Unmapped Error","description":"The `error` is an integer indicating a SMSC and/or network specificerror straight from the SMPP PDUs.","value":{"id":"01GA3CSYKJAB5QW8AMHQNJMT9D","recipient":4512345678,"reference":"","status":"undeliverable","status_at":"2022-08-10T08:12:35.901468+00:00","error":"smsc_error:1"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"receive-mobile-origin-sms":{"post":{"summary":"Receive Mobile Origin Sms","description":"Receive a mobile origin sms.\n\nThe responding server _must_ respond with a status code in the successful\nrange between `200` and `299`, in order to mark the event as delivered.\n\nAny other responses will we treated as a failure to deliver and will cause\nthe event to be retried again later.","operationId":"receive_mobile_origin_smsreceive_mobile_origin_sms_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MobileOriginSMS-Input"},"examples":{"minimal-example":{"summary":"A minimal example","value":{"id":"01GA3CSYKJAB5QW8AMHQNJMT9D","text":"Hello World!","recipient":451234,"sender":"4512345678","sent_at":"2022-08-10T08:12:35.901468+0000","encoding":"gsm7"}},"unicode-support":{"summary":"Unicode support","value":{"id":"01GA3CSYKJAB5QW8AMHQNJMT9D","text":"Unicode Rocks! 🤘","recipient":451234,"sender":"4512345678","sent_at":"2022-08-10T08:12:35.901468+0000","encoding":"ucs2"}},"binary-message":{"summary":"Binary Message","description":"Note that the `text` is now encoded as hexadecimal.","value":{"id":"01GA3CSYKJAB5QW8AMHQNJMT9D","text":"48656C6C6F20576F726C6421","recipient":451234,"sender":"4512345678","sent_at":"2022-08-10T08:12:35.901468+0000","encoding":"binary"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"DeliveryReport":{"properties":{"id":{"type":"string","title":"Id"},"recipient":{"type":"integer","title":"Recipient"},"reference":{"type":"string","title":"Reference"},"status":{"$ref":"#/components/schemas/Status"},"status_at":{"type":"string","format":"date-time","title":"Status At","description":"Timestamp for when the status was received by the SMSC.\nUses the format:\n- `YYYY-MM-DDTHH:MM:SS[.ffffff][+ or -]HH:MM`.\n"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["id","recipient","reference","status","status_at","error"],"title":"DeliveryReport","description":"Representation of a delivery report as a webhook callback.\n\nWhenever a message changes state in the systems attempts to deliver it to the\nreceiving device, an event is generated and will be attempted to be sent back\nto the system that submitted the message to begin with."},"Encoding":{"type":"string","enum":["gsm7","ucs2","binary"],"title":"Encoding","description":"Enumeration of possible message encodings."},"ErrorDetail":{"properties":{"msg":{"type":"string","title":"Msg"}},"type":"object","required":["msg"],"title":"ErrorDetail","description":"Details for the error returned."},"ErrorResponse":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ErrorDetail"},"type":"array","title":"Detail"}},"type":"object","required":["detail"],"title":"ErrorResponse","description":"Response model for all API errors."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LogDlrResponse":{"properties":{"next":{"type":"string","format":"date-time","title":"Next","description":"Timestamp to be used in the next API call to get the following status reports.\nAccepts the format:\n- `YYYY-MM-DDTHH:MM:SS[.ffffff][+ or -]HH:MM`.\n"},"reports":{"items":{"$ref":"#/components/schemas/DeliveryReport"},"type":"array","title":"Reports"}},"type":"object","required":["next","reports"],"title":"LogDlrResponse","description":"Object returned when requesting a log of delivery reports.","examples":[{"next":"2023-01-27T09:42:03.032000+00:00","reports":[{"error":"smsc error code: 1","id":"01GQS9NXZT87LZV8XR8CB92KKU","recipient":4512345678,"reference":"submitted-reference","status":"expired","status_at":"2023-01-27T09:42:01.793000+00:00"},{"id":"01GQS9NZ1SSDE6RYMKPR5K06C9","recipient":4512345678,"reference":"1234","status":"delivered","status_at":"2023-01-27T09:42:03.032000+00:00"}]}]},"LogMOResponse":{"properties":{"next":{"type":"string","format":"date-time","title":"Next","description":"Timestamp to be used in the next API call to get the following mesages.\nAccepts the format:\n- `YYYY-MM-DDTHH:MM:SS[.ffffff][+ or -]HH:MM`.\n"},"messages":{"items":{"$ref":"#/components/schemas/MobileOriginSMS-Output"},"type":"array","title":"Messages"}},"type":"object","required":["next","messages"],"title":"LogMOResponse","description":"Object returned when requesten a log of mobile originated messages.","examples":[{"messages":[{"id":"01ARZ3NDEKTSV4RRFFQ69G5FAV","recipient":451234,"sender":"4512348765","sent_at":"2023-06-27T09:42:01.793000+00:00","text":"Hello"},{"id":"01ARZ34DEKTSV4RRFFQ69G5FXV","recipient":451234,"sender":"4512348765","sent_at":"2023-06-28T09:42:01.793000+00:00","text":"Hello again"}],"next":"2023-01-27T09:42:03.032000+00:00"}]},"MobileOriginSMS-Input":{"properties":{"id":{"type":"string","title":"Id"},"text":{"type":"string","title":"Text","description":"The contents of the SMS, this needs to be dealt with according to the `encoding` field, notably a `binary` SMS will have the bytes formatted as hexadecimal."},"header":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Header"},"recipient":{"type":"integer","title":"Recipient"},"sender":{"type":"string","title":"Sender"},"sent_at":{"type":"string","format":"date-time","title":"Sent At"},"msg_type":{"$ref":"#/components/schemas/MsgType"},"encoding":{"$ref":"#/components/schemas/Encoding"},"expiration":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expiration"}},"type":"object","required":["id","text","header","recipient","sender","sent_at","msg_type","encoding","expiration"],"title":"MobileOriginSMS","description":"Representation of a mobile origin SMS.\n\nWhenever a device sends a message to a virtualnumber you have configured,\nthat message gets processed and sent as an MO SMS, that we will try and\ndeliver as a webhook event."},"MobileOriginSMS-Output":{"properties":{"id":{"type":"string","title":"Id"},"text":{"type":"string","title":"Text","description":"The contents of the SMS, this needs to be dealt with according to the `encoding` field, notably a `binary` SMS will have the bytes formatted as hexadecimal."},"recipient":{"type":"integer","title":"Recipient"},"sender":{"type":"string","title":"Sender"},"sent_at":{"type":"string","format":"date-time","title":"Sent At"}},"type":"object","required":["id","text","recipient","sender","sent_at"],"title":"MobileOriginSMS","description":"Representation of a mobile origin SMS.\n\nWhenever a device sends a message to a virtualnumber you have configured,\nthat message gets processed and sent as an MO SMS.\n\nThis variant from stored in our logs differs slightly from the webhook\nversion as it does not have the following fields:\n- `header`\n- `msg_type`\n- `encoding`\n- `expiration`"},"MsgType":{"type":"string","enum":["normal","flash"],"title":"MsgType","description":"Enumeration of possible message types.\n\nBy far the most common should be `normal` but it is possible to encounter\n`flash`."},"ShortMessageResponse":{"properties":{"id":{"type":"string","title":"Id","description":"The gateway/SMSC provided ID of the submitted Short Message."}},"type":"object","required":["id"],"title":"ShortMessageResponse","description":"Object returned when submitting messages."},"ShortMessageSubmit":{"properties":{"encoding":{"$ref":"#/components/schemas/Encoding","description":"The encoding used for the message. `gsm7` uses a limited character set, while `ucs2` allows a far wider selection of characters, but also uses at least 2 bytes per code point.\n`binary` is used to indicate a binary message, often used for communications between hardware or servers.\n\nWhen using `binary` the `text` value has to be encoded using hexadecimal characters.\n\nNote that regardless of the encoding used the `text` field has to be submitted as UTF-8."},"text":{"type":"string","maxLength":39015,"minLength":1,"title":"Text","description":"Actual text of the message. The encoded length of the message is affected by the `encoding` selected.\n\nNote that no matter the selected encoding, the `text` should _always_ be UTF-8 encoded."},"recipient":{"type":"integer","maximum":1.8446744073709552e+19,"title":"Recipient","description":"Has to be parsable to an MSISDN.\nValues over 15 digits are unlikely to work, but larger values are accepted for compatibility reasons. Values over uint64 are rejected as absolutely unreasonable."},"sender":{"type":"string","title":"Sender","description":"Has to be at least 1 and most either 11 characters alphanumeric or 15 numeric characters.\n\nAlphanumeric characters has to be limited to the Unicode Basic Multilingual Plane. Letters and numbers outside `[A-Za-z0-9]` have a greater risk of being replaced or removed during processing by the systems in the chain of delivery."},"header":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Header","description":"User data header (often just UDH) bytes formatted as hexadecimal.\n\nSending a long message combined with a header will result in undefined behaviour."},"expiration":{"anyOf":[{"type":"string","format":"duration"},{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expiration","description":"Point in time, or time until the message expires.\nAccepts several formats:\n- ISO-8601 duration.\n- `YYYY-MM-DD[T]HH:MM:SS[.ffffff][Z or [+ or -]HH[:]MM]`.\n- Unix timestamp in seconds.\n- Seconds offset, if the value is less than or equals 432000.\n\nNo matter which format is used, the expiration cannot be more than 5 days in the future.\n\nIf left unset a default value of 5 days into the future will be used."},"msg_type":{"$ref":"#/components/schemas/MsgType","default":"normal"},"reference":{"anyOf":[{"type":"string","maxLength":512,"minLength":1},{"type":"null"}],"title":"Reference","description":"Client provided opaque reference. Used when submitting webhook events back to the client service, often used for matching DLRs to a SMS."}},"additionalProperties":false,"type":"object","required":["encoding","text","recipient","sender"],"title":"ShortMessageSubmit","description":"Single recipient Short message.\n\nThis collection of fields presents a reasonable high-level interface for\nsubmitting messages into the SMSC gateway, while still allowing for some\nlower level features supported by the SMPP specification.\n\nNote that hexadecimal is used in favour of base64 or even base85, for binary\ndata, as the compactness benefits are limited with lengths that SMS\ntypically transmit, while hexadecimal should be reasonably easy to use in\nmost languages."},"Status":{"type":"string","enum":["accepted","deleted","delivered","buffered","enroute","expired","rejected","undeliverable","unknown"],"title":"Status","description":"Enumeration of possible message delivery states.\n\nIncludes states found in the SMPP specification but also states that\noccasionally get used in the DLR text which can be more flexible than\nthe regular states.\n\nThe most common states should be `enroute`, `delivered`, `rejected`,\n`expired`, and `undeliverable`."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"token":{"type":"apiKey","description":"Fill the `Authorization` header with the value, using the authorization scheme `Token` followed by a space and the value.\n\nSuch as: `Token NG.pHPP9heEha_mUQ4SJ42kX3JFTqp89VPW`.","in":"header","name":"authorization"}}}}