Send a verification code to a sender address
Emails a six-digit code to the address in the body and records a
pending claim. Complete it with
POST /v1/verified-senders/{id}/confirm.
This sends real email from SendOps' own mail service — not from
your SES account — to whatever address you name. Rate-limited to five
starts an hour per user. Grant api.inboxes.manage with that in mind.
Why bother. An inbox whose allowed_senders are all verified is
restricted, and a restricted inbox is exempt from the mint quota and
the per-credential cap. Verifying one address is the difference between
three inboxes a day and an unmetered supply.
202, not 201: the row exists but the address is not verified and
cannot be until somebody reads the mailbox.
Calling it again for the same address replaces the code and resets the attempt counter, which is also how a claim locked by five wrong codes is unlocked. The rate limit is what stops that being a way around the lock.
Requires a user-delegated token, for the reason the list route gives.
The code is never in a response, an error, or a log.
Request body
Content type: application/json
email string required A plain address you can read — you@example.com. A display name (You <you@example.com>) is refused, because the intake path's sender check compares addresses and a stored display name would produce an inbox that silently matched nothing.
Responses
Errors follow the RFC 7807 problem format — see the error reference.
id string<uuid> required email string required The address, lower-cased. PII.
status string enum required locked means five wrong codes; the way out is a fresh POST /v1/verified-senders, not a sixth guess.
One of: pending, locked, verified
code_expires_at string<date-time> optional When the outstanding code lapses, 15 minutes after it was sent. Absent on a verified claim — confirming clears the code.
verified_at string<date-time> optional Present once the code came back. This is what the mint path asks about.
created_at string<date-time> required code: invalid_scope), or it is bound to the test environment and this operation is irreversible (code: test_environment_forbidden). Branch on code: the first is fixed by granting the scope, the second only by using a live credential. See the "Live and test credentials" section of the API description. application/problem+json code is conflict.
application/problem+json validation_failed Problem. When the refusal is about a
reference — a segment key, template slug, topic or attribute name the
organization does not have — it additionally carries validation_code,
field, line/column, missing, candidates and next_step, so a
client can correct the call without a second round of guessing. See
ValidationProblem.
application/problem+json code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json