Tag and Filter Emails with Metadata

What is email metadata in the Nylas CLI?

Email metadata is a set of custom key-value pairs you attach to a message at send time, separate from its headers, subject, or body. Nylas stores up to 50 pairs per message and reserves five of them — key1 through key5 — as indexed, filterable fields. Metadata is your application's data, not the recipient's, and it never appears in the email itself.

This solves a real problem: correlating a sent message back to the thing that triggered it. Without metadata you stuff a tracking token into the subject, parse it back with a regex, and pray the recipient doesn't edit it on reply. With metadata you tag the send once and query it back exactly. According to the Nylas v3 email docs, metadata is set when sending or creating a draft and cannot be changed on an existing message — so the tag you write is immutable for that send.

How do I tag an email with metadata when I send it?

Tag an outbound message by repeating the --metadata flag once per pair on nylas email send. Each flag takes a key=value argument, and the send delivers over your connected provider's API — no SMTP host or label setup. You can attach as many as 50 pairs in one call.

The command below stamps a campaign name, a tenant ID, and a request ID on a single send. Use --yes to skip the confirmation prompt in scripts. The metadata is written once at delivery and stays attached to that message for its lifetime.

nylas email send \
  --to customer@example.com \
  --subject "Your March invoice" \
  --body "Invoice attached. Reply with any questions." \
  --metadata key1=invoice \
  --metadata key2=acct_8841 \
  --metadata key3=req_5f2a \
  --yes

Pair metadata with --track-opens or --track-links to correlate open and click events back to the same request ID in your logs. The tool also accepts metadata on a hosted template send, so a templated receipt can carry the order ID that generated it.

Why are only five metadata keys filterable?

Only key1 through key5 are filterable because Nylas indexes exactly those five keys for query performance. You can store up to 50 pairs per message, but the other 45 are payload — readable when you fetch a message, not searchable in a list query. This is the single rule that decides whether a tag is queryable at all, so plan your key names before you send.

The practical design: put the dimensions you filter on into key1–key5, and put descriptive extras into named keys. A campaign send might use key1 for the campaign type and key2 for the tenant, while a key like source carries a human-readable note you only read, never filter. The nylas email metadata info command prints these limits on demand, so you never have to guess which keys are indexed.

# Print the indexed-key rules and limits
nylas email metadata info

How do I filter emails by metadata later?

Filter messages by passing --metadata key:value to nylas email list. The filter accepts only the indexed keys key1–key5, and the format uses a colon, not the equals sign you used on send. The query runs server-side, so the provider returns only matching messages instead of every message in the folder.

The first command lists every message tagged as an invoice. The second adds --json and pipes through jq to pull message IDs for a single tenant — useful for batching follow-up actions. Filtering happens at the API layer in one round trip, not by downloading and grepping locally.

# List every message tagged key1=invoice
nylas email list --metadata key1:invoice

# Get IDs for one tenant as JSON, ready to pipe into a batch action
nylas email list --metadata key2:acct_8841 --json | jq -r '.[].id'

To inspect every pair on a specific message — indexed and named alike — run nylas email metadata show <message-id>. That returns all 50 possible pairs, which the list filter never sees.

When should I use metadata instead of labels or folders?

Use metadata when the tag is your application's data and labels when it is the user's organization. Labels and folders are provider-native and recipient-visible: a Gmail label appears in the recipient's mailbox, and Microsoft Graph categories surface in Outlook. Metadata is invisible to the recipient and consistent across every provider you connect, which is why it fits machine correlation, not human filing.

There are real trade-offs. A Gmail label, documented in the Gmail API labels guide, is searchable in the recipient's own client; metadata is not. A Microsoft Graph message resource exposes categories that sync to the user's mailbox. Metadata wins when you need a stable, cross-provider, recipient-invisible key that you can attach at send and query back in one API call — campaign IDs, tenant IDs, and request correlation are the typical cases.

Next steps

• Organize emails by company — group and route inbound mail by sender domain
• Search email from the terminal — combine subject, sender, and date filters with metadata queries
• Extract email data with jq — parse the JSON your metadata filters return into fields and IDs
• Send email with templates — attach a campaign or order ID to a templated transactional send
• Extract contact details from signatures — another structured-data workflow over the same inbox
• Command reference — every flag, subcommand, and example
• Nylas v3 email metadata docs — the indexed-key rules and 50-pair limit