Issue another pull URL for an inbox
Issues one more credential-free URL onto an inbox that already exists, and returns it ONCE.
What a pull URL is. An address on the fetch host that reads this inbox's status and messages with no SendOps credential of any kind. You give it to one of your own users; they never authenticate with SendOps, because you already did. It is read-only — it cannot delete the inbox, change it, or reach any other inbox — but ANYONE HOLDING IT READS THE MAIL. Revoking it is how you take that back.
Why you would call this rather than reuse the mint's URL. Only the token's hash is stored, so the URL returned at mint cannot be looked up again. Issue a new one for a user who lost the link, or a second one for a second reader, then revoke whichever you no longer want.
Ten live URLs per inbox at most; the eleventh is 422 with code
pull_token_limit. Revoked ones do not count.
The body is optional. label is a note for telling several URLs apart
and is never matched against anything — do not put your user's email in
it, which is what account_ref exists to avoid.
An expired inbox is 410: there is no mail left to read, so a URL onto
it would open nothing. A deleted one, or one this credential cannot
see, is 404.
Path parameters
id string<uuid> required The inbox's UUID, exactly as returned by POST /v1/inboxes. A value that is not a UUID is a 404 rather than a 422 — it names nothing, and saying "that is not a valid UUID" would confirm the format of ids that do exist.
Request body
Content type: application/json
label string optional A note for telling several URLs on one inbox apart. Matched against nothing, and never a place for your user's address.
Constraints: length 0–80
Responses
Errors follow the RFC 7807 problem format — see the error reference.
id string<uuid> required What you revoke by. Pass it as token_id to DELETE /v1/inboxes/{id}/pull-tokens/{token_id}.
prefix string required The first characters of the token body, display only. Safe in a log line, a dashboard column or a screenshot, which is the whole reason it exists — it identifies a URL without being one.
label string required Your note, for telling several URLs on one inbox apart. Matched against nothing. Not a place for your user's email — that is what account_ref is for.
Constraints: length 0–80
created_at string<date-time> required revoked_at string<date-time> | null required Null while the URL still opens the inbox. A timestamp rather than a boolean because "when was this URL cut off" is the question an incident asks.
pull_url string<uri> required The URL itself, returned ONCE. Anyone holding it reads this inbox's mail without a SendOps credential, which is what makes it useful to give to an end user and what makes revoking it the only way to take it back. No route returns it again.
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
gone.
This is the expected end of a poll loop, not an error to investigate:
expires_at has been in every response for this id since it was
minted. Mint another inbox to receive more mail.
A DELETED inbox answers 404 instead — deletion is the owner asking us
to forget it, so we do not then confirm it existed.
application/problem+json code separates
them:
- pull_token_limit — the inbox already has ten live pull URLs.
Nothing about the request was wrong; the same call succeeds after
DELETE /v1/inboxes/{id}/pull-tokens/{token_id} frees a slot.
- validation_failed — the body was not a JSON object, or label was
too long.
application/problem+json code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json