Get an OTP message
Read the current mirrored status of a message sent through the OTP API. A status is a delivery outcome, not successful code verification. Explicit status corrections can clear a recorded failure. The supplied code is never returned.
Unknown query parameters are rejected. Omit the request body; only an absent body or an empty object is accepted.
Responses
| Status | Meaning and codes |
|---|---|
| 200 | Current message status and details in your workspace. |
| 401 | Problem Details. Codes: API_KEY_INVALID. |
| 404 | Problem Details. Codes: NOT_FOUND. |
| 422 | Problem Details. Codes: DEVELOPER_INVALID_INPUT. |
| 429 | Problem Details. Codes: RATE_LIMITED. Retry-After: 1 is present only for RATE_LIMITED; quota errors do not include it. |
Success and handled error responses send Cache-Control: no-store and X-Correlation-ID (the resolved/generated UUID). Errors use application/problem+json and the reusable ProblemDetails schema below. Retry-After: 1 is sent only for RATE_LIMITED. Request examples read your key from a server environment variable; replace all fictional values.
Schemas and examples
ApiKeyAuthorizationBearer <token>Server-side API key. publicId is 12 lowercase base32 characters (a-z, 2-7); secret is 43 base64url characters from 32 random bytes. Use Authorization: Bearer <complete key>. The API key determines the workspace; requests cannot select another workspace. All public routes share 20 requests per second per key. See API-key authentication.
messageId*stringMessage ID in your workspace, returned when you send an OTP message.
uuidX-Correlation-ID?stringOptional tracing ID. A UUID-shaped value is echoed in the response. Missing or invalid values are replaced with a generated UUID, not rejected.
Current message status and details in your workspace.
application/json- response
messageId*stringMessage ID.
uuidstatus*stringCurrent mirrored status. played belongs to the shared vocabulary; it is not an expected OTP text outcome.
"accepted""received""queued""sending""sent""delivered""read""played""failed"reference*|Caller reference, or null if omitted.
to*stringNormalized E.164 recipient.
createdAt*stringLedger creation time.
date-timesentAt*|First sent/delivered/read/played occurrence, or null.
date-timefailure*|null