---
title: "Send yourself a test code"
method: POST
path: "/inboxes/{id}/test-code"
tags: ["inboxes"]
---

# Send yourself a test code

`POST /inboxes/{id}/test-code`

## Request

- Base URL: `https://dash.mailsocket.app/api/v1`
- URL: `https://dash.mailsocket.app/api/v1/inboxes/{id}/test-code`
- Auth: HTTP bearer

Puts one sample OTP email (a random 6-digit code) straight into one of
your own inboxes. It does NOT go through the mail server: the message
is stored and parsed exactly like real inbound mail, so a pending
`messages/wait` returns it, it counts toward the monthly message
usage and it fires the inbox's webhook. Use it to prove the wait loop
end to end when you cannot send real email (for example, outbound
port 25 is blocked).

To run the steps one call at a time (no second shell), take a cutoff
BEFORE this call and pass it to the wait as `since`: read
`GET /inboxes/{id}/messages/latest` and use its `data.id` (or `0` when it
returns `404` because the inbox is empty), then call test-code, then
`GET /inboxes/{id}/messages/wait?require=otp&since=<that id>`. The wait
returns this test code even though it arrived before the wait started,
and never an older code already in the inbox. Without `since`, the wait
only sees mail that arrives while it runs, so then start the wait first
and call test-code from another shell while it is pending.

Same feature and the same limits as the dashboard "Send a test code"
button, and the two share one quota: 5 per inbox and 20 per account
per hour. The per-inbox limit is checked first, so a refused request
never uses up the account-wide budget. Foreign, deleted and unknown
inbox ids all return the same `404`, and nothing is charged.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Response `201`

The test code was stored. It is parsed within a moment.

- object
  - `data` object, required
    - `message_id` string, required: Public id of the new message (`msg_...`).
    - `sent_at` string, date-time, required: When the message was stored (its `received_at`).

## Other responses

- `400`: The `Idempotency-Key` header is empty, longer than 255 characters, or not printable ASCII, or the request body is too large to read with an `Idempotency-Key`.
- `401`: Missing or invalid API key.
- `403`: Account is not permitted to use the API.
- `404`: Resource not found (unknown or not owned).
- `409`: The inbox is disabled (`inbox_disabled`; enable it first), or a request with the same `Idempotency-Key` is still running (`idempotency_in_progress`).
- `422`: The `Idempotency-Key` was already used with a different body or endpoint (`idempotency_key_reused`), or the request body failed validation.
- `429`: Per-inbox (5/hour) or per-account (20/hour) test-code limit reached (shared with the dashboard button). `error.message` says how many minutes until another test code can be sent; `Retry-After` gives the same moment in seconds.

---

[API](https://skmtc.dev/mailsocket/apis/mailsocket-api.md) · [All operations](https://skmtc.dev/mailsocket/apis/mailsocket-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailsocket/apis/mailsocket-api/revisions/e579500dfb7e?raw)