sent-analytics
Sent Analytics
Use numbers.lookup, dashboard.messages_sent, dashboard.deliverability, and dashboard.contacts for analytics and paid external number lookup. numbers.lookup is state-changing and non-idempotent, even though it does not send a message.
Establish context
Use client-managed OAuth 2.1/PKCE. Never request or expose a token, API key, authorization header, client ID, or secret. Identify the active organization and Sender Profile when the client exposes them.
Minimize sensitive output: mask phone numbers, aggregate where possible, and omit contact, KYC, account, and message-body data that is not needed to answer the question.
An organization grant may select an owned Sender Profile with the tool schema's optional profileId; omit it to act as the authenticated account. Validate ownership with sender_profiles.list or sender_profiles.get, and use the same selector for preflight reads, mutations, and follow-up reads. Profile grants cannot use this selector. Reauthorize for a different organization or a profile outside the grant. Never invent scope fields or request credentials.
Look up a number
Use numbers.lookup to obtain available capability, formatting, type, or routing signals for the supplied number. A lookup describes capability; it is not evidence of opt-in, consent, ownership, identity, or permission to message. State that distinction whenever the result could be used to plan outreach. The paid lookup allowance is 1000 calls per authenticated account scope per UTC day, shared across acting profiles and resetting at 00:00 UTC. Respect quota errors; do not rotate profiles or retry in a loop. Temporary quota-check failure can allow lookup through, which does not make it free.