--- title: "Create & poll email addresses from the CLI | WebhookRelay" meta: "og:description": "Use the relay CLI to create inbound email addresses and read the messages they receive — one command to create, then poll the bucket for parsed JSON." "og:title": "Create & poll email addresses from the CLI" description: "Use the relay CLI to create inbound email addresses and read the messages they receive — one command to create, then poll the bucket for parsed JSON." --- ![Stripes](https://webhookrelay.com/images/stripes.svg)
Documentation **Create & poll email addresses from the CLI** # **Create & poll email addresses from the CLI** Use the relay CLI to create inbound email addresses and read the messages they receive — one command to create, then poll the bucket for parsed JSON. The [`relay` CLI](https://webhookrelay.com/docs/installation/cli/) can create inbound email addresses and consume the messages they receive, without opening the dashboard. It's the quickest way to grab a throwaway inbox, wire an address into a script, or watch mail arrive in your terminal. Two commands do the work: - **`relay email create`** — create an inbound address (optionally on a fresh throwaway bucket). - **`relay events`** — pull the parsed emails from the bucket as they arrive. > You need the CLI installed and authenticated first — see [Install the CLI](https://webhookrelay.com/docs/installation/cli/). All commands accept a bucket by **name or ID**. ## [Create an address](#create-an-address) The fastest path — no arguments — creates a throwaway bucket and prints a ready-to-use address: ``` $ relay email create Inbound email address created. Address: eb9649a3-b781-4158-be69-bb210596e759@in.webhookrelay-mail.com Bucket: email-c8e44869 (9bf342ce-9582-42ea-8662-ac73d60e2db6, created for you) Input: eb9649a3-b781-4158-be69-bb210596e759 Poll it with: relay events --bucket email-c8e44869 --follow ``` The address is the input's ID at your environment's inbound domain (`@in.webhookrelay-mail.com`). Send mail to it and every message is parsed into [JSON](https://webhookrelay.com/docs/email/payload/) and stored on the bucket. Attach the address to an **existing bucket** with `--bucket`, and restrict who may send with `--filter-from` (repeatable; exact-match [sender allowlist](https://webhookrelay.com/docs/email/filtering-and-policy/)): ``` # Into an existing bucket, only accept mail from one sender relay email create --bucket signups --filter-from noreply@stripe.com # Several allowed senders, drop attachments, give it a name relay email create --bucket signups \ --name "stripe-receipts" \ --filter-from alerts@stripe.com \ --filter-from ci@stripe.com \ --no-attachments ``` For scripts, `--json` prints the address and IDs as JSON: ``` $ relay email create --bucket signups --name stripe-receipts --filter-from noreply@stripe.com --json { "email_address": "15a51b42-7de4-42ff-8628-4645565fa8b1@in.webhookrelay-mail.com", "input_id": "15a51b42-7de4-42ff-8628-4645565fa8b1", "bucket_id": "9bf342ce-9582-42ea-8662-ac73d60e2db6", "bucket_name": "signups", "allowed_senders": ["noreply@stripe.com"] } # Capture just the address $ ADDR=$(relay email create --json | jq -r .email_address) ``` **When you don't pass **`--bucket`**, **`relay email create`** provisions a throwaway bucket for the address. If the address can't be created afterwards, that throwaway bucket is cleaned up automatically — a bucket you pass with **`--bucket`** is never removed.** ### [`relay email create` flags](#relay-email-create-flags) | Flag | Description | | --- | --- | | `-b, --bucket ` | Bucket to attach the address to. A throwaway bucket is created if omitted. | | `--name ` | Friendly name for the email input. | | `--filter-from ` | Only accept mail from this sender (repeatable; exact, case-insensitive match). | | `--no-attachments` | Drop attachments instead of storing them. | | `--json` | Output the created address as JSON. | ## [List addresses in a bucket](#list-addresses-in-a-bucket) Lost an address? List a bucket's inbound addresses: ``` $ relay email list --bucket signups ADDRESS NAME FILTER STATUS 15a51b42-7de4-42ff-8628-4645565fa8b1@in.webhookrelay-mail.com stripe-receipts noreply@stripe.com - eb9649a3-b781-4158-be69-bb210596e759@in.webhookrelay-mail.com - any sender - ``` Add `--json` for the full objects (including `email_input` policy). ## [Poll for email](#poll-for-email) `relay events` consumes the bucket's **pull-delivery queue**: each call returns the emails that haven't been delivered yet and marks them delivered, so repeated calls drain the queue. Inbound emails show up with their sender and subject: ``` $ relay events --bucket signups ID AGE FROM SUBJECT 373e52cb-764e-4f0f-9c8f-6b1e2a0d9f11 6 seconds noreply@stripe.com Your receipt ``` Use `--follow` (like `tail -f`) to block and print new emails as they land: ``` relay events --bucket signups --follow ``` Pull a larger batch, look further back, or restrict to a single output: ``` # Up to 50 per poll, looking back 1 hour relay events --bucket signups --limit 50 --max-age 1h # Only events routed to a specific output relay events --bucket signups --output out_1a2b ``` ### [Scripting](#scripting) `--json` emits the full event objects; `--body` emits just the parsed-email JSON (one per line), which is handy for piping into `jq`: ``` # Extract sender + subject of each email relay events --bucket signups --json | jq '.[].body | fromjson | {from, subject}' # Stream raw parsed emails relay events --bucket signups --body # Only the event IDs (e.g. to feed into \`relay inspect\`) relay events --bucket signups -q ``` ### [`relay events` flags](#relay-events-flags) | Flag | Description | | --- | --- | | `-b, --bucket ` | Bucket to consume from (required). | | `--output ` | Only consume events for this output ID. | | `--limit ` | Max events per poll (max 100; CLI default 20). | | `--max-age ` | How far back to look for undelivered events (Go duration, e.g. `1h`; server default 24h). | | `-f, --follow` | Keep polling and print new events as they arrive. | | `--interval ` | Poll interval when following (default `2s`). | | `--json` | Output full event objects as JSON. | | `--body` | Print only the raw event bodies (parsed email JSON). | | `--format ` | Pretty-print events using a Go template. | | `-q, --quiet` | Only display event IDs. | ### [How polling works](#how-polling-works) `relay events` is a **consuming** queue: returning an email to you _is_ its delivery, so each row is marked delivered (`RECEIVED → SENT`) before the response is sent and won't appear on the next poll. This makes it a reliable "process each email once" channel: - The queue **drains** — keep polling (or use `--follow`) until you get an empty page. - If you consumed an email but failed to handle it, correct the outcome afterwards with `relay api` (`PUT /v1/logs/{id}`) so it can be retried. - For a **non-destructive** view of everything a bucket received, use `relay logs` and `relay inspect` instead — they read the audit log without consuming. ## [Related](#related) - [Receive emails as webhooks](https://webhookrelay.com/docs/email/) — the feature overview and dashboard flow. - [Email webhook payload](https://webhookrelay.com/docs/email/payload/) — every field your events contain. - [Sender filtering & policy](https://webhookrelay.com/docs/email/filtering-and-policy/) — allowlists, attachments, limits. - [Install the CLI](https://webhookrelay.com/docs/installation/cli/) — get the `relay` binary. Did this page help you?