OneShot SDK Code Examples - Email, Voice, Build & More

Initialize

CDP Wallet (Recommended)
Private Key

import { OneShot } from "@oneshot-agent/sdk";

// No private keys — signing in Coinbase's secure enclave
const agent = await OneShot.create({ cdp: true });

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({
  privateKey: process.env.AGENT_PRIVATE_KEY,
});

All examples below work with either initialization method.

Send Email

// Simple email
await agent.email({
  to: "[email protected]",
  subject: "Hello from OneShot",
  body: "This email was sent autonomously!",
});

// Email with attachments
await agent.email({
  to: "[email protected]",
  subject: "Report attached",
  body: "Please find the report attached.",
  attachments: [
    {
      filename: "report.pdf",
      content: base64Content,
      content_type: "application/pdf",
    },
  ],
});

// Custom sender — display name, mailbox, and domain.
// Renders as: From: Jane Doe <[email protected]>
await agent.email({
  to: "[email protected]",
  subject: "Hello",
  body: "Sent from a custom sender.",
  from_name: "Jane Doe",     // display name (optional)
  from_mailbox: "jane",      // local-part, defaults to "agent"
  from_domain: "acme.com",   // defaults to "oneshotagent.com"
});

from_domain must be a domain you’ve provisioned through OneShot. from_mailbox defaults to agent and from_domain to oneshotagent.com, so the default sender is [email protected]. from_name is the human-readable name recipients see; omit it to send from the bare address.

Dedicated mailboxes — pass mailbox_mode: "mailbox" when first provisioning a new from_domain to give each address a real dedicated mailbox (better deliverability + per-address warmup) instead of the default relay (header-only) send. It adds a one-time mailbox_provisioning_fee to the quote. It only applies at first setup — an already-provisioned domain keeps the mode it was created with, and requesting mailbox on an existing relay domain returns 400 mailbox_mode_conflict.The corollary is the part that surprises people: never passing mailbox_mode doesn’t make your sends relay sends. If a domain was set up in mailbox mode, every address on it that isn’t already active bills the one-time fee on its first send — the default agent@ included. Call listDomains() and read mailbox_mode per domain to see which of yours charge; from_mailbox has no bearing on it.

Bulk Email

Send the same email to multiple recipients:

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({
  privateKey: process.env.AGENT_PRIVATE_KEY,
});

// Send to multiple recipients
await agent.email({
  to: ["[email protected]", "[email protected]", "[email protected]"],
  subject: "Weekly Team Update",
  body: "Here is this week's progress report...",
});

// Each recipient gets an individual email (not CC/BCC)

The SDK automatically handles bulk quoting and pricing. Service fees scale with the number of recipients.

Voice Calls

Make phone calls that can accomplish objectives autonomously:

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({
  privateKey: process.env.AGENT_PRIVATE_KEY,
});

// Simple call - make a restaurant reservation
const result = await agent.voice({
  objective: "Make a dinner reservation for 2 at 7pm tonight",
  target_number: "+14155551234",
  caller_persona: "A polite assistant making a reservation",
  context: "Italian restaurant, prefer outdoor seating",
});

console.log("Transcript:", result.transcript);
console.log("Summary:", result.summary);
console.log("Success:", result.success_evaluation);

// Conference call - connect multiple parties
const conference = await agent.voice({
  objective: "Connect the buyer and seller to negotiate the final price",
  target_number: ["+14155551234", "+14155555678"],
  caller_persona: "A professional meeting facilitator",
});

SMS Messages

Send text messages to one or multiple recipients:

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({
  privateKey: process.env.AGENT_PRIVATE_KEY,
});

// Single recipient
const result = await agent.sms({
  message: "Your order has shipped! Track it at example.com/track/123",
  to_number: "+14155551234",
});

// Multiple recipients (up to 10)
const bulkResult = await agent.sms({
  message: "Team meeting moved to 3pm",
  to_number: ["+14155551234", "+14155555678", "+14155559012"],
});

// Check SMS inbox for replies
const inbox = await agent.smsInboxList({ limit: 10 });

for (const msg of inbox.messages) {
  console.log(`From ${msg.from}: ${msg.body}`);
}

// Get a specific message
const message = await agent.smsInboxGet("msg_abc123");

Deep Research

// Quick research (5-10 sources, 2-3 minutes)
const quickReport = await agent.research({
  topic: "Latest developments in AI agents",
  depth: "quick",
});

console.log(quickReport.report_content);
console.log(`Sources: ${quickReport.sources_count}`);

// Comprehensive research (20+ sources, 5-10 minutes)
const deepReport = await agent.research({
  topic: "Blockchain scalability solutions",
  depth: "deep",
});

console.log(deepReport.report_content);
console.log(`Report saved to: ${deepReport.report_gcs_uri}`);

Poll Inbox

// List recent emails
const inbox = await agent.inboxList({
  include_body: true,
  limit: 10,
});

for (const email of inbox.emails) {
  console.log(`From: ${email.from}`);
  console.log(`Subject: ${email.subject}`);
  console.log(`Body: ${email.body}`);

  // Process attachments
  if (email.attachments) {
    for (const att of email.attachments) {
      const buffer = Buffer.from(att.content, "base64");
      // Process attachment...
    }
  }
}

// Get emails since a specific time
const recentInbox = await agent.inboxList({
  since: "2024-01-01T00:00:00Z",
  include_body: true,
});

// Get a specific email by ID
const specificEmail = await agent.inboxGet("email-id-here");

People Search & Enrichment

// Search for people by criteria
const results = await agent.peopleSearch({
  job_titles: ["CEO", "CTO", "VP Engineering"],
  company_domains: ["stripe.com", "anthropic.com"],
  location: ["San Francisco"],
  limit: 20,
});

console.log(`Found ${results.total_found} people`);

for (const person of results.results) {
  console.log(`${person.full_name} - ${person.title} at ${person.company}`);

  // Enrich profile for more details
  const profile = await agent.enrichProfile({
    linkedin_url: person.linkedin_url,
  });

  console.log(`Skills: ${profile.profile.skills?.join(", ")}`);
}

Email Finder & Verification

// Find email for a person
const found = await agent.findEmail({
  full_name: "Dario Amodei",
  company_domain: "anthropic.com",
});

if (found.found) {
  console.log(`Found email: ${found.email}`);

  // Verify before sending
  const verification = await agent.verifyEmail({
    email: found.email,
  });

  if (verification.deliverable) {
    await agent.email({
      to: found.email,
      subject: "Hello",
      body: "Your message here...",
    });
  }
}

Commerce - Search & Buy

// Search for products
const products = await agent.commerceSearch({
  query: "USB-C hub multiport",
  limit: 5,
});

console.log(`Found ${products.count} products`);

// Buy the first result
const order = await agent.commerceBuy({
  product_url: products.products[0].product_url,
  shipping_address: {
    first_name: "John",
    last_name: "Doe",
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    zip_code: "94102",
    country: "US",
    phone: "4155550100",
    email: "[email protected]",
  },
  quantity: 1,
  maxCost: 100, // Fail if total exceeds $100
});

console.log(`Order submitted: ${order.request_id}`);

Web Search

Search the web and get structured results instantly (synchronous — no polling):

// Quick web search
const results = await agent.webSearch({
  query: "best AI agent frameworks 2026",
  max_results: 10,
});

for (const result of results.results) {
  console.log(`${result.title}: ${result.url}`);
}

Web Read

Read any web page and get markdown content with a screenshot:

// Read a web page
const page = await agent.webRead({
  url: "https://news.ycombinator.com",
});

console.log(page.markdown);          // Page content as markdown
console.log(page.screenshot_url);    // Screenshot of the page
console.log(page.metadata.title);    // Page title

Browser Automation

Navigate websites, fill forms, extract structured data, and interact with web apps:

// Extract structured data from a website
const result = await agent.browser({
  task: "Go to producthunt.com and extract the top 5 AI products launched today",
  output_schema: {
    products: [{
      name: "string",
      description: "string",
      upvotes: "number"
    }]
  }
});

console.log("Products:", result.output.products);
console.log("Steps taken:", result.steps.length);
console.log("Cost:", result.cost, "USDC");

// Resume a previous browser session (preserves cookies/login state)
const followUp = await agent.browser({
  task: "Click on the first product and extract the full description",
  session_id: result.session_id,
});

Person Intelligence

Look up anyone by email, name, or social URL. Each method runs async and returns when the job finishes.

// Full background report on a person (takes 2-5 minutes)
const dossier = await agent.deepResearchPerson({
  email: "[email protected]",
  name: "Satya Nadella",
  company: "Microsoft",
});

// Emails and phones are nested inside result.enrichment
const enrichment = dossier.result.enrichment;
console.log("Work email:", enrichment.best_work_email);
console.log("Personal email:", enrichment.best_personal_email);
console.log("All emails:", enrichment.altemails);
console.log("Phone:", enrichment.fullphone?.[0]?.fullphone);
console.log("Company:", enrichment.organizations?.[0]?.name);
console.log("LinkedIn:", enrichment.social_profiles?.linkedin?.url);

// Articles from the deep research
console.log("Articles:", dossier.result.articles);

// Find their accounts on LinkedIn, Twitter, GitHub, etc
const socials = await agent.socialProfiles({
  email: "[email protected]",
});

console.log(socials.result);

// Articles and interviews mentioning them
const articles = await agent.articleSearch({
  name: "Satya Nadella",
  company: "Microsoft",
  sort: "recent",
  limit: 5,
});

console.log(articles.result);

// Recent posts with likes, replies, shares
const feed = await agent.personNewsfeed({
  social_media_url: "https://twitter.com/satyanadella",
});

console.log(feed.result);

// What they care about (sports, tech, politics, etc)
const interests = await agent.personInterests({
  email: "[email protected]",
});

console.log(interests.result);

// Who they follow and who follows them
const interactions = await agent.personInteractions({
  social_media_url: "https://twitter.com/satyanadella",
  type: "followers,following",
  max_results: 50,
});

console.log(interactions.result);

Universal Tool Method

Call any OneShot tool using the universal tool() method:

// Email quote
const quote = await agent.tool("email/quote", {
  from_address: "[email protected]",
  to_address: "[email protected]",
  subject: "Test",
  body: "Hello",
});

console.log(`Cost: $${quote.total_cost}`);

// Email send (with quote ID)
const send = await agent.toolWithQuote(
  "email/send",
  {
    from_address: "[email protected]",
    to_address: "[email protected]",
    subject: "Test",
    body: "Hello",
  },
  quote.quote_id,
);

Check Wallet Balance

const agent = new OneShot({
  privateKey: process.env.AGENT_PRIVATE_KEY,
});

console.log("Agent address:", agent.address);

const balance = await agent.getBalance(agent.usdcAddress);
console.log(`Wallet balance: ${balance} USDC`);

if (parseFloat(balance) < 1.0) {
  console.warn("Low balance! Please fund your wallet.");
}

The agent.usdcAddress getter returns the USDC contract address on Base Mainnet: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

Spend Budgets

Cap what the agent can spend per day and per call. Enforced by the API, so the cap survives restarts and is shared across every process using this wallet:

import { OneShot, BudgetExceededError } from "@oneshot-agent/sdk";

const agent = await OneShot.create({
  cdp: true,
  budgets: { daily: 50, perTransaction: 5, alertAt: 0.8 },
  alerts: { email: "[email protected]" },
});

try {
  await agent.research({ topic: "competitor pricing", memo: "weekly scan" });
} catch (err) {
  if (err instanceof BudgetExceededError) {
    // reason: "daily" | "per_transaction"; nothing was charged
    console.warn(`Budget ${err.reason} hit — $${err.spent} spent today, resumes ${err.resetsAt}`);
  } else {
    throw err;
  }
}

const status = await agent.budgets();
console.log(`${(status.pct_used! * 100).toFixed(0)}% of today's budget used`);

Error Handling

import {
  OneShot,
  ContentBlockedError,
  EmergencyNumberError,
  BudgetExceededError,
} from "@oneshot-agent/sdk";

try {
  await agent.sms({
    message: "Your appointment is confirmed",
    to_number: "+14155551234",
  });
} catch (error) {
  if (error instanceof ContentBlockedError) {
    // Message flagged by content safety
    console.error("Content blocked:", error.categories);
  } else if (error instanceof EmergencyNumberError) {
    // Attempted to contact emergency services
    console.error("Emergency number blocked:", error.blockedNumber);
  } else if (error instanceof BudgetExceededError) {
    // The agent's own spend budget stopped the call; nothing was charged
    console.error(`Budget ${error.reason} exceeded, resets ${error.resetsAt}`);
  } else if (error.message.includes("Insufficient balance")) {
    console.error("Not enough funds in wallet");
  } else if (error.message.includes("domain_unavailable")) {
    console.error("Domain is not available");
  } else {
    console.error("Error:", error.message);
  }
}

Build Production Websites

Generate and deploy fully-functional websites from product descriptions:

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({
  privateKey: process.env.AGENT_PRIVATE_KEY,
});

// Build a SaaS landing page
const result = await agent.build({
  type: "saas",
  product: {
    name: "TaskFlow",
    description: "AI-powered task management for remote teams. Automate workflows, track progress, and collaborate seamlessly.",
    industry: "Productivity",
    pricing: "Free tier, Pro $12/mo, Team $29/mo"
  },
  lead_capture: { enabled: true },
  brand: {
    primary_color: "#4F46E5",
    tone: "professional"
  }
});

console.log("Website live at:", result.production_url);
console.log("Preview:", result.preview_url);

Update Existing Website

Iterate on an existing website with new content:

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({
  privateKey: process.env.AGENT_PRIVATE_KEY,
});

// Update with new content
const result = await agent.updateBuild({
  build_id: "550e8400-e29b-41d4-a716-446655440000", // from original build
  product: {
    name: "TaskFlow 2.0",
    description: "Now with AI automation! Task management reimagined for modern teams.",
    pricing: "Free tier, Pro $15/mo, Team $35/mo"
  }
});

console.log("Updated:", result.production_url);

Complete Agent Example

import { OneShot } from "@oneshot-agent/sdk";

class EmailAgent {
  private agent: OneShot;
  private lastCheck: string;

  private constructor(agent: OneShot) {
    this.agent = agent;
    this.lastCheck = new Date().toISOString();
  }

  static async create() {
    // CDP wallet — no private keys in config
    const agent = await OneShot.create({ cdp: true });
    return new EmailAgent(agent);
  }

  async start() {
    console.log(`Agent started: ${this.agent.address}`);

    // Poll inbox every minute
    setInterval(() => this.pollInbox(), 60000);
  }

  async pollInbox() {
    try {
      const inbox = await this.agent.inboxList({
        since: this.lastCheck,
        include_body: true,
        limit: 50,
      });

      if (inbox.count > 0) {
        console.log(`Received ${inbox.count} new email(s)`);

        for (const email of inbox.emails) {
          await this.processEmail(email);
        }

        this.lastCheck = new Date().toISOString();
      }
    } catch (error) {
      console.error("Error polling inbox:", error);
    }
  }

  async processEmail(email: any) {
    console.log(`Processing email from ${email.from}`);

    const reply = await this.generateReply(email);

    await this.agent.email({
      to: email.from,
      subject: `Re: ${email.subject}`,
      body: reply,
    });

    console.log(`Replied to ${email.from}`);
  }

  async generateReply(email: any): Promise<string> {
    // Use your LLM here to generate a reply
    return `Thank you for your email. I'll get back to you soon!`;
  }
}

// Start the agent
const agent = await EmailAgent.create();
agent.start();

Get Started

SDK

OneShot SDK Code Examples - Email, Voice, Build & More

Initialize

Send Email

Bulk Email

Voice Calls

SMS Messages

Deep Research

Poll Inbox

People Search & Enrichment

Email Finder & Verification

Commerce - Search & Buy

Web Search

Web Read

Browser Automation

Person Intelligence

Universal Tool Method

Check Wallet Balance

Spend Budgets

Error Handling

Build Production Websites

Update Existing Website

Complete Agent Example

Next Steps

API Reference

SDK Source

​Initialize

​Send Email

​Bulk Email

​Voice Calls

​SMS Messages

​Deep Research

​Poll Inbox

​People Search & Enrichment

​Email Finder & Verification

​Commerce - Search & Buy

​Web Search

​Web Read

​Browser Automation

​Person Intelligence

​Universal Tool Method

​Check Wallet Balance

​Spend Budgets

​Error Handling

​Build Production Websites

​Update Existing Website

​Complete Agent Example

​Next Steps

API Reference

SDK Source

Initialize

Send Email

Bulk Email

Voice Calls

SMS Messages

Deep Research

Poll Inbox

People Search & Enrichment

Email Finder & Verification

Commerce - Search & Buy

Web Search

Web Read

Browser Automation

Person Intelligence

Universal Tool Method

Check Wallet Balance

Spend Budgets

Error Handling

Build Production Websites

Update Existing Website

Complete Agent Example

Next Steps