Wait for a message

Receiving is implemented; public availability is not confirmed today.

1. Send a test messageCopy Anchor Link

   This endpoint sends real mail even with a test key; the received message keeps the inbox's mode. Use a new Idempotency-Key for each test; reuse it only when retrying that test.

   Copy Text

   curl -X POST https://api.sendtier.com/v1/inboxes/ibx_MZXW6YTBOI/test-message \
     -H "Authorization: Bearer $SENDTIER_API_KEY" \
     -H 'Idempotency-Key: signup-inbox-test-1'

   Save wait_after and subject from the response as WAIT_AFTER and TEST_SUBJECT. Acceptance does not confirm receipt. The body contains code 123456 and one link. Today, limits are 5 test messages per recipient address and 20 per account in any rolling 60 minutes. Today, a shared platform limit also allows 300 in that window. A full key is required. For 429 rate_limited, wait for Retry-After before retrying. Unverified receiving returns 422 domain_receiving_disabled; missing platform mailer settings or a failed platform send return 503 unavailable.

2. Wait for itCopy Anchor Link

   Pass wait_after as after and the returned subject as subject_contains.

   Copy Text

   curl --get https://api.sendtier.com/v1/inboxes/ibx_MZXW6YTBOI/messages/wait \
     -H "Authorization: Bearer $SENDTIER_API_KEY" \
     --data-urlencode "after=$WAIT_AFTER" \
     --data-urlencode 'timeout=30' \
     --data-urlencode "subject_contains=$TEST_SUBJECT"

   You get 200 with message metadata, or an empty 204 after the timeout (1–30 seconds). Repeat with the same after after a 204. Set your HTTP client timeout above the wait timeout. Disconnecting cancels the wait; reconnect with the same after. No message is consumed. A deleted or expired after message returns 400 invalid_request; start again without after. Too many concurrent waits return 429 rate_limited; retry with backoff.

Test your own app's emailCopy Anchor Link

Create an inbox first. Start the wait before your app sends. Without after, a wait accepts only messages that arrive after it starts. Use a live sender: a test key never delivers mail.

A late delivery can arrive before your cursor. List messages again to find missed mail.

FiltersCopy Anchor Link

from matches an exact sender, ignoring case. subject_contains matches a literal substring, ignoring case.

Wait for a message reference · Read codes and links.