Designing a Developer API for Sending and Receiving Text Messages at Twilio

Design Twilio's SMS API: the interface developers call to send text messages from their applications and to receive the replies. ```hint Follow the message after the call returns A text is not finished when the send request comes back. Think about what the developer still needs to learn about that message later, and how that information should reach them. ``` ### Clarifying Questions - Which developers come first: engineers at large enterprises sending high volumes, or small teams and low-code builders who want a working text within minutes? - Which use cases are in scope: one-off transactional texts such as verification codes, notifications to many recipients, two-way conversations, or all of them? - Is this a new API, or a redesign of an existing one where current integrations must keep working? - Is the scope SMS only, or should the design leave room for picture messages and other messaging channels? ### What a Strong Answer Covers - Target developer segments and the core jobs the API must support, with a reasoned priority - The resource model and endpoints for sending, retrieving and listing messages and for inbound messages, with request parameters and responses - How the asynchronous delivery lifecycle reaches developers (callbacks versus polling), plus retries, duplicates and idempotency - Carrier and developer realities: authentication, sender numbers, error design, rate limits, message length, opt-outs and sender registration - Success metrics such as time to first message and delivery rate, and the trade-offs behind the main design choices ### Follow-up Questions - A customer wants to send the same alert to hundreds of thousands of recipients at once. Would you add a bulk endpoint or have them call the single-send endpoint in a loop, and why? - A developer's callback endpoint is down for an hour. What happens to the status updates and inbound messages generated in that time? - How would you measure whether the developer experience of the API is getting better from one release to the next?