If your product already speaks GraphQL, you can expose texting as a sendMessage mutation that your resolver turns into one call to POST /v1/messages. Your clients never see the SMS API key, your schema stays the one contract they code against, and the REST details live in a single resolver. The work is in the edges: idempotency, error mapping and consent.

We make Ready, so the REST calls below use our documented request shape. The GraphQL side is yours to design, and the same pattern works in front of any SMS API.

When a wrapper is worth it

A wrapper is a small service you now own. It's worth it when:

  • Your web and mobile apps already talk to one GraphQL endpoint and you don't want a second client for SMS.
  • You need your own authorization (who in which tenant may text whom) before anything reaches the provider.
  • You want to change providers or add rules later without touching every client.

It's not worth it for a backend job that sends a nightly batch. Call the REST API from that job directly, as in our guide to sending SMS from Node.js.

Design the mutation around your product

Don't mirror the REST body field for field. Expose what a client legitimately decides, and fill in the rest on the server.

input SendMessageInput {
  contactId: ID!
  body: String!
  idempotencyKey: ID!
}

type SendMessageSuccess { messageId: ID! }
type SendMessageRefused { code: RefusalCode!, retryable: Boolean! }

enum RefusalCode { OPTED_OUT, QUIET_HOURS, CONSENT_MISSING, RATE_LIMITED, UNAVAILABLE, INVALID }

union SendMessagePayload = SendMessageSuccess | SendMessageRefused

type Mutation {
  sendMessage(input: SendMessageInput!): SendMessagePayload!
}

A few choices here are deliberate. The client passes a contactId, not a phone number, so your resolver can look up the number and the consent record itself. The client supplies an idempotencyKey, generated once per user action, so a double tap or a retried request never sends twice. And the result is a union of success and refusal types rather than a thrown error, so a refusal is data the client can render.

The resolver: one call, one key

const resolvers = {
  Mutation: {
    async sendMessage(_, { input }, ctx) {
      const contact = await ctx.contacts.getForTenant(ctx.tenantId, input.contactId);
      if (!contact || !contact.hasTextConsent) {
        return { __typename: 'SendMessageRefused', code: 'CONSENT_MISSING', retryable: false };
      }

      const res = await fetch('https://api.tryready.com/v1/messages', {
        method: 'POST',
        headers: {
          'X-API-Key': ctx.readyApiKey,
          'Content-Type': 'application/json',
          'Idempotency-Key': input.idempotencyKey,
        },
        body: JSON.stringify({
          to: contact.phoneE164,
          body: input.body,
          consent_attested: true,
        }),
        signal: AbortSignal.timeout(35000), // above Ready's own 30 s send deadline
      });

      return mapResponse(res);
    },
  },
};

Two things to notice. consent_attested is true only because the resolver checked your own consent record first; never let a client set it. And the API key comes from server-side context, looked up for that tenant, so it never travels to a browser. Until January 20, 2027 (UTC) a send without consent_attested still goes out with a warning and no attestation recorded, and from that date the API refuses it with 403 api_consent_attested_required.

Map REST statuses to GraphQL outcomes

GraphQL answers HTTP 200 even when something failed, so the status mapping is what gives clients a real signal.

REST outcomeYour payloadRetryable
2xx with success not false and not heldSendMessageSuccessn/a
202 with success: false (send_outcome_unknown), 504, or 409 *_outcome_unknownCHECK_FIRSTno: look the message up with GET /v1/messages first, never resend under a new key
409 idempotency_in_progressUNAVAILABLEyes, with the same key after a pause
429RATE_LIMITEDyes, after a pause
5xx or timeoutUNAVAILABLEyes, with the same key
409 QUIET_HOURS_BLOCKQUIET_HOURSyes, once the window opens
403 api_consent_attested_requiredCONSENT_MISSINGno; fix your data
other 4xxINVALIDno

An opted-out number is refused up front and not charged, and you can show that as OPTED_OUT. The full list of codes is in the API error reference, and our post on SMS API error codes and troubleshooting explains how to triage them. Log the raw status and body on your side, and don't pass the provider's text straight to end users.

Reading messages: use a cursor connection

GET /v1/messages pages with before_id, which maps neatly onto a GraphQL connection.

type Query {
  messages(before: ID, limit: Int = 25): MessageConnection!
}
type MessageConnection {
  nodes: [Message!]!
  nextBefore: ID
}

Your resolver passes before through as before_id and returns the last id as nextBefore. For anything real-time, don't poll through GraphQL. Take the delivery status webhook into your own service and push changes to clients with a subscription; our post on a realtime SMS inbox with webhooks and SSE shows the transport.

Things that bite

  • Retries inside the resolver. If you retry a failed REST call, reuse the same Idempotency-Key. If the client retries the mutation, the same idempotencyKey flows through. Either way the number of texts stays at one.
  • Batching. A list of contacts in one query tempts you into N calls. For many recipients, expose a separate mutation that calls POST /v1/messages/bulk, which takes a limited number of recipients per call, and split larger lists into batches.
  • Authorization depth. Check the tenant on every resolver, not just the top one. A client that guesses a contactId from another tenant must get nothing.
  • Timeouts. Set one shorter than your gateway's, so a slow upstream becomes a clean UNAVAILABLE rather than a client hang. See circuit breakers and timeouts for an SMS API.

Takeaways

Keep the schema about your product, keep the key and consent decisions on the server, and map every REST outcome to a typed result. The wrapper should be thin enough that you could rewrite it in an afternoon. The messages reference is in the messages API docs; when you want to try the mutation against a real account, sign up and send a first text.