Skip to content

feat(integrate): add MailVeri verified outreach sample - #347

Open
mailveri wants to merge 3 commits into
strands-agents:mainfrom
mailveri:add-mailveri-verified-outreach
Open

mailveri wants to merge 3 commits into
strands-agents:mainfrom
mailveri:add-mailveri-verified-outreach

Conversation

@mailveri

Copy link
Copy Markdown

Issue #, if available: None

Description of changes:

Adds a Python integration sample at python/03-integrate/tools/mailveri: a single Strands agent that verifies every prospect email with MailVeri before it drafts outreach. I am connected to MailVeri.

The sample shows two Strands patterns that are useful beyond email:

  • Class-based @tool methods with shared state. MailVeriTools exposes verify_emails, get_credit_balance and save_draft as bound tools, and they share the run's verification results.
  • A guard enforced in a tool, not only in the prompt. save_draft rejects any address that was not verified in this run or whose decision is not send, so a model mistake cannot produce a draft for an invalid or unconfirmed address.

How it works:

  • verified_outreach.py loads prospects.example.csv (or --prospects), builds a Bedrock-backed agent (default us.anthropic.claude-sonnet-4-6, overridable with BEDROCK_MODEL_ID) and runs it.
  • verify_emails calls the documented POST https://api.mailveri.com/v1/verify-mail/ endpoint once per address, with a short pause to stay under the documented rate limit. VALID maps to send; INVALID, DISPOSABLE and FULL_INBOX to skip; ROLE_ACCOUNT, CATCH_ALL and UNKNOWN to review (role and catch-all can be opted in with env flags). If the account runs out of credits, it stops and returns the unchecked addresses.
  • Nothing is sent. Drafts go to drafts.csv and every decision to verification_log.csv.
  • The README also shows the alternative of loading the MailVeri MCP server with MCPClient via uvx.

Repository changes outside the sample folder:

  • samples.json: regenerated with node generate-samples-manifest.mjs.
  • generate-samples-manifest.mjs: one TITLE_WORDS entry (mailveri: 'MailVeri') so the generated title is not "Mailveri". Happy to drop it if you prefer.
  • The sample is not added to a collection in samples-catalog.json, so it stays repository-only like the other 03-integrate/tools samples.

The sample follows .github/templates/use-cases/ (basic script structure, README template sections, security notes and disclaimer). The architecture is a Mermaid diagram in the README instead of a PNG.

Testing:

  • uv sync and uv run --group dev pytest tests: 20 passed on Python 3.10 and 3.13 with strands-agents 1.64.0. All MailVeri HTTP is mocked with respx; the tests cover the decision table, out-of-credits and auth errors, the save_draft gate, tool registration on a real Agent, and a direct agent.tool.verify_emails(...) call.
  • ruff check and ruff format --check: clean.
  • node --test generate-samples-manifest.test.mjs and node generate-samples-manifest.mjs --check: pass.
  • The MCP snippet was run locally: MCPClient started the server with uvx and listed its tools.
  • Not done: an end-to-end run against Amazon Bedrock and the live MailVeri API.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant