smsv2.openapi.json

{"openapi":"3.0.1","info":{"title":"Gateway SMS","description":"The Gateway SMS API by Openapi provides a robust and scalable solution for integrating professional SMS messaging into your applications. Our service is designed to handle high volumes of messages with precision, offering dedicated endpoints for specific regions like Italy and Spain, as well as a Worldwide endpoint for global reach.\n\nEach request undergoes a rigorous validation process that includes syntax checking for E.164 formats, character encoding detection (GSM-7 or UCS-2), and automatic segmentation for long messages. We prioritize security and compliance: the system automatically scans content for forbidden words to prevent abuse and ensures that all messages comply with legal requirements.\n\nDevelopers can benefit from advanced features such as 'Dry Run' for testing without incurring costs, and real-time Webhook callbacks that provide immediate updates on delivery status. Messages have a maximum expiration time of 48 hours; if a message cannot be delivered within this window, its status will change to EXPIRED. Billing is transparent and dynamic; while regional messages have fixed rates, worldwide delivery costs are calculated post-sending to ensure the best market price. Please note that maintaining a minimum credit balance is required for worldwide operations, and strict penalties apply for policy violations to ensure the highest quality of service for all users.","version":"1.2.7","contact":{"url":"https://openapi.it/en/support","name":"Support"},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"},"termsOfService":"https://openapi.it/en/terms-and-conditions"},"externalDocs":{"description":"First time here? Generate a new access token","url":"https://console.openapi.com/oauth"},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://sms.openapi.com","description":"Production"},{"url":"https://test.sms.openapi.com","description":"Sandbox"}],"tags":[{"name":"Messages","description":"Operations for sending and retrieving SMS messages."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SendMessageRequest":{"type":"object","description":"Request body for sending a new SMS message.","required":["recipient","message"],"properties":{"sender":{"type":"string","nullable":true,"description":"The message sender. Must be an alphanumeric Alias (between 3 and 11 chars, spaces allowed) and cannot be purely numeric. If null or empty, 'Openapi' will be used as the default sender.","minLength":3,"maxLength":11,"default":"Openapi","example":"MyCompany"},"recipient":{"type":"string","description":"The recipient's number in international E.164 format.","example":"+393331234567"},"message":{"type":"string","description":"The text of the message to be sent. Segmentation is handled automatically. GSM-7 encoding allows up to 160 characters per part (153 if multi-part), while UCS-2 allows up to 70 characters (67 if multi-part).","example":"Hello! This is a test message."},"options":{"$ref":"#/components/schemas/MessageOptions"},"callback":{"$ref":"#/components/schemas/CallbackOptions"}}},"SendOTPRequest":{"type":"object","description":"Request body for sending an OTP verification message.","required":["recipient"],"properties":{"recipient":{"type":"string","description":"The recipient's number in international E.164 format.","example":"+393331234567"},"alphanumeric":{"type":"boolean","description":"If set to 'true', the generated OTP will be alphanumeric. If 'false' (default), it will be purely numeric.","default":false},"length":{"type":"integer","description":"The length of the OTP code (min 4, max 10).","minimum":4,"maximum":10,"default":5},"cacheSeconds":{"type":"integer","description":"The number of seconds within which the same OTP code will be reused for the same recipient (max 600).","minimum":0,"maximum":600,"default":0},"options":{"$ref":"#/components/schemas/MessageOptions"},"callback":{"$ref":"#/components/schemas/CallbackOptions"}}},"MessageOptions":{"type":"object","properties":{"dryRun":{"type":"boolean","description":"If set to 'true', the request is validated and calculated, but the message is not actually sent.","default":false},"failOnMultipleMessages":{"type":"boolean","description":"If set to 'true', the request will fail if the message text exceeds the length of a single SMS part.","default":false}}},"CallbackOptions":{"type":"object","description":"This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.","properties":{"method":{"type":"string","description":"Specify the callback method. When set to 'POST', a standard HTTP POST request will be initiated with the Content-Type header set to application/x-www-form-urlencoded. The JSON data will be encoded into a key-value pair named data (customizable using the field parameter) within the request body. If the method is set to 'JSON', a direct HTTP POST request will be made with the Content-Type header set to application/json. The raw JSON data will be directly inserted into the request body without any encoding.","enum":["POST","JSON"],"default":"JSON"},"field":{"type":"string","description":"This parameter works in conjunction with the 'method' parameter set to 'POST'. When provided as a string, it determines the name of the parameter that will be sent in the POST request.","example":"data","default":"data"},"url":{"type":"string","format":"uri","description":"A valid URL capable of handling POST requests must be entered into this parameter. For endpoints requiring authentication, the 'headers' parameter can be used to specify 'basic auth' or 'bearer auth'. The maximum timeout is 30 seconds. If 'retry' is set, the system will retry up to 'retry' times until a 200 status code is received.","example":"https://www.mysite.com/myEndpoint"},"retry":{"type":"integer","description":"The maximum number of attempts is defined by the 'retry' parameter. If the maximum number of attempts is reached without a successful status code (e.g., 200 OK), the request is considered a final failure. A time interval is often introduced between attempts to avoid overloading the server. This interval may increase exponentially with each attempt to reduce the impact on an overloaded server. The 'retry' parameter is configured to retry the request only in case of specific status codes, typically those indicating temporary errors (e.g., 502, 503) or network issues.","example":3,"maximum":5,"minimum":0,"default":0},"headers":{"type":"object","properties":{"key":{"type":"string"}},"description":"A collection of HTTP headers to be sent with the request. Each header is defined as a key-value pair. Headers can be used for various purposes, including authentication, content negotiation, and custom metadata.","example":{"session_id":"9834r5fh589494"}},"custom":{"type":"object","description":"This object can be populated with any additional data you wish to include in the callback response. This data will be accessible within the 'custom' parameter of the callback function. You can use this to store and retrieve any relevant information that you need for your application.","example":{"my_custom_id":"123456789"}}},"required":["url"]},"OTPOptions":{"type":"object","description":"Configuration used for the OTP generation.","properties":{"length":{"type":"integer","description":"Length of the OTP code.","example":5},"alphanumeric":{"type":"boolean","description":"If the code is alphanumeric.","example":false},"cacheSeconds":{"type":"integer","description":"Cache duration for the OTP.","example":300}}},"MessageResponse":{"type":"object","description":"Object representing a message.","properties":{"id":{"type":"string","description":"The unique ID of the message in our system.","example":"633aabe3e4a9a0e69811ad7f"},"username":{"type":"string","description":"Username of the account that sent the message."},"state":{"type":"string","description":"The current state of the message. The maximum expiration time for delivery attempts is 48 hours. If a message cannot be delivered within this window, its status will change to EXPIRED.","enum":["NEW","PENDING","UNDELIVERABLE","DELIVERED","EXPIRED","REJECTED"]},"sender":{"type":"string","nullable":true,"description":"The sender used for the delivery."},"recipient":{"type":"string","description":"The recipient of the message."},"internationalPrefix":{"type":"string","description":"The international prefix of the recipient's number.","example":"39"},"countryCode":{"type":"string","description":"The ISO country code of the recipient.","example":"IT"},"message":{"type":"string","description":"The text of the sent message."},"encoding":{"type":"string","description":"The encoding detected for the message.","enum":["GSM-7","UCS-2"]},"charactersCount":{"type":"integer","description":"The number of characters calculated according to the encoding rules."},"messageCount":{"type":"integer","description":"The number of SMS segments required to send the message."},"price":{"type":"number","format":"float","default":0,"description":"The cost per single SMS part. For WW messages, this is initially 0 and updated after provider acceptance."},"totalPrice":{"type":"number","format":"float","default":0,"description":"The total cost of the message (price * messageCount). For WW messages, this is initially 0 and updated after provider acceptance."},"blocklisted":{"type":"boolean","description":"Indicates if the message was blocked due to forbidden content."},"blocklistedReason":{"type":"string","description":"The reason why the message was blocklisted (if applicable)."},"options":{"$ref":"#/components/schemas/MessageOptions"},"callback":{"$ref":"#/components/schemas/CallbackOptions"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"sentAt":{"type":"string","format":"date-time","nullable":true},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"isOtp":{"type":"boolean","description":"Indicates if the message is an OTP."},"otp":{"type":"string","description":"The generated OTP code (only present for OTP requests).","example":"5F8A2"},"otpOptions":{"$ref":"#/components/schemas/OTPOptions"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","description":"An internal error code for quick problem identification."},"message":{"type":"string","description":"A clear description of the error."}}}}},"paths":{"/WW-messages":{"post":{"tags":["Messages"],"summary":"Send a new SMS message (Worldwide)","description":"Creates and queues a new SMS message for worldwide sending. Please note that for this endpoint, the message cost will be calculated and charged only after the message has been sent. The final price varies depending on the recipient's operator.\n\nIf the user has an active subscription plan, the message parts will be deducted from the available bundle before charging any remaining balance from the wallet.\n\nTo send a message via this endpoint, you must have a minimum credit on your account equal to 1 EUR multiplied by the number of message parts (messageCount) in case a bundle is not available or insufficient.\n\nIMPORTANT: If the message content or sender contains forbidden words, the message will be blocked, the account will be blocklisted, and a penalty fee of 1 EUR per message part will be charged.","requestBody":{"description":"Data of the message to be sent.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"201":{"description":"Message Accepted and Queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageResponse"}}}}}},"403":{"description":"Forbidden (e.g., user is blocklisted)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":2020,"message":"The user is blocklisted. Please contact support for assistance."}}}},"422":{"description":"Unprocessable Entity (e.g., invalid data format, forbidden words)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Invalid Sender":{"value":{"code":2021,"message":"Sender alias must be between 3 and 11 alphanumeric characters."}},"Numeric Sender":{"value":{"code":2024,"message":"Sender alias cannot be purely numeric."}},"Invalid Recipient":{"value":{"code":2011,"message":"Invalid mobile phone number. Use E.164 format."}},"Forbidden Content":{"value":{"code":2044,"message":"The sent message does not comply with the legal requirements."}}}}}}}}},"/IT-messages":{"post":{"tags":["Messages"],"summary":"Send a new SMS message (Italy)","description":"Creates and queues a new SMS message for sending specifically to Italy. Applies country-specific rules and pricing.\n\nIMPORTANT: If the message content or sender contains forbidden words, the message will be blocked, the account will be blocklisted, and the cost of the message will be charged.","requestBody":{"description":"Data of the message to be sent.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"201":{"description":"Message Accepted and Queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageResponse"}}}}}},"403":{"description":"Forbidden (e.g., user is blocklisted)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":2020,"message":"The user is blocklisted. Please contact support for assistance."}}}},"422":{"description":"Unprocessable Entity (e.g., invalid data format, forbidden words, wrong country)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Wrong Country":{"value":{"code":2013,"message":"The recipient number does not belong to the supported country for this endpoint (IT)."}},"Forbidden Content":{"value":{"code":2050,"message":"The sent message does not comply with the legal requirements."}},"Forbidden Content (Dry Run)":{"value":{"code":2044,"message":"The sent message does not comply with the legal requirements."}}}}}}}}},"/ES-messages":{"post":{"tags":["Messages"],"summary":"Send a new SMS message (Spain)","description":"Creates and queues a new SMS message for sending specifically to Spain. Applies country-specific rules and pricing.\n\nIMPORTANT: If the message content or sender contains forbidden words, the message will be blocked, the account will be blocklisted, and the cost of the message will be charged.","requestBody":{"description":"Data of the message to be sent.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"201":{"description":"Message Accepted and Queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageResponse"}}}}}},"403":{"description":"Forbidden (e.g., user is blocklisted)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":2020,"message":"The user is blocklisted. Please contact support for assistance."}}}},"422":{"description":"Unprocessable Entity (e.g., invalid data format, forbidden words, wrong country)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Wrong Country":{"value":{"code":2013,"message":"The recipient number does not belong to the supported country for this endpoint (ES)."}},"Forbidden Content":{"value":{"code":2050,"message":"The sent message does not comply with the legal requirements."}},"Forbidden Content (Dry Run)":{"value":{"code":2044,"message":"The sent message does not comply with the legal requirements."}}}}}}}}},"/otp":{"post":{"tags":["Messages"],"summary":"Send an OTP verification message","description":"Generates a secure OTP code and sends it via SMS to the recipient using 'OTP MOBILE' as the default sender. The message body is automatically translated based on the recipient's country. Pricing follows the Worldwide (WW) model.","requestBody":{"description":"Data for the OTP message.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendOTPRequest"}}}},"responses":{"201":{"description":"OTP Sent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageResponse"}}}}}},"403":{"description":"Forbidden (e.g., user is blocklisted)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":2020,"message":"The user is blocklisted. Please contact support for assistance."}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Invalid Length":{"value":{"code":1020,"message":"Length must be between 4 and 10."}},"Invalid Recipient":{"value":{"code":2011,"message":"Invalid mobile phone number. Use E.164 format."}}}}}}}}},"/messages":{"get":{"tags":["Messages"],"summary":"Retrieve the list of sent messages","description":"Returns a paginated list of messages sent from your account.","parameters":[{"name":"skip","in":"query","description":"Number of messages to skip for pagination.","schema":{"type":"integer","default":0}},{"name":"limit","in":"query","description":"Maximum number of messages to return.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Operation successful","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MessageResponse"}}}}}}},"401":{"description":"Unauthorized"}}}},"/messages/{id}":{"get":{"tags":["Messages"],"summary":"Retrieve a single message","description":"Returns the details of a specific message via its ID.","parameters":[{"name":"id","in":"path","description":"The unique ID of the message to retrieve.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation successful","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageResponse"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Message Not Found"}}}}}}