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

Initialize once.

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,
});

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 provisioned through OneShot. from_mailbox defaults to agent and from_domain to oneshotagent.com. from_name is the display 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 dedicated mailbox (better deliverability, per-address warmup) instead of the default relay (send-only) mode. This adds a one-time mailbox_provisioning_fee to the quote. It applies only at first setup: a provisioned domain keeps the mode it was created with, and requesting mailbox on an existing relay domain returns 400 mailbox_mode_conflict.Omitting mailbox_mode does not make your sends relay sends. On a domain set up in mailbox mode, every address not already active bills the one-time fee on its first send, including the default agent@. Call listDomains() and read mailbox_mode per domain to see which charge. from_mailbox has no effect on it.

Bulk email

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 handles bulk quoting. Service fees scale with the number of recipients.

Voice calls

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

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);

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 and enrichment

// Search for people by criteria
const results = await agent.personFind({
  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.personProfile({
    linkedin_url: person.linkedin_url,
  });

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

seniority takes any of owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern. Common variants ("Vice President", "C-Level", "executive") are accepted, and a value that matches no level fails the search with invalid_input. industry is free text. An empty results array means the search ran and nobody matched. If the search could not be run, the call throws a JobError with a retryable code (service_unavailable, service_auth, rate_limited) instead of returning an empty result.

Find and verify email

// Find email for a person
const found = await agent.personEmail({
  name: "Dario Amodei",
  company: "Anthropic",
});

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

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

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

Commerce: search and buy

// Search for products
const products = await agent.productFind({
  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 the cap
});

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

Web search

Search the web and get structured results synchronously, without 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 a web page as markdown, 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

// 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 a person by name+company, email, phone or profile URL. Each method runs async and returns when the job finishes.

// Person profile, known social accounts, articles, posts and written summary (takes 2-5 minutes)
const dossier = await agent.personDossier({
  email: "[email protected]",
  name: "Satya Nadella",
  company: "Microsoft",
  timeout: 300, // seconds; the dossier takes a few minutes
});

// Emails and phones are nested inside result.profile.data
const enrichment = dossier.result.profile.data;
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.company);
console.log("LinkedIn:", enrichment.linkedin_url);

// Check each section state before consuming its data
console.log("Profile, known social accounts, articles, posts and written summary:", dossier.result);

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

console.log(socials.result);

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

console.log(articles.result);

// Recent posts with likes, replies, shares
const feed = await agent.personPosts({
  name: "Satya Nadella",
  company: "Microsoft",
});

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.personFollowers({
  profile_url: "https://x.com/satyanadella",
  type: "followers,following",
  max_results: 50,
});

console.log(interactions.result);

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,
);

Get 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 the agent’s spend per day and per call. The API enforces the cap, so it survives restarts and applies 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

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

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();

Next steps

API Reference

API reference

SDK Source

SDK source

Optional phone lookup

const people = await agent.personFind({ job_titles: ['CTO'], limit: 3, includePhone: true, maxCost: 1, waitForPhones: true });
const profile = await agent.personProfile({ email: '[email protected]', includePhone: true, maxCost: 1, waitForPhones: true });
const dossier = await agent.personDossier({ email: '[email protected]', includePhone: true, maxCost: 1, waitForPhones: true, timeout: 600 });

waitForPhones waits without purchasing phones. onStatusUpdate('completed', requestId) fires after this wait, before resolution; phones_pending: true may remain on timeout.

people = client.person_find(job_titles=["CTO"], limit=3, include_phone=True, max_cost=1, wait_for_phones=True)
profile = await client.aperson_profile(email="[email protected]", include_phone=True, max_cost=1, wait_for_phones=True)
dossier = await client.aperson_dossier(email="[email protected]", include_phone=True, max_cost=1, wait_for_phones=True, timeout_sec=600)

Get Started

Organizations

SDK

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

Initialize

Email

Bulk email

Voice calls

SMS

Deep research

Poll inbox

People search and enrichment

Find and verify email

Commerce: search and buy

Web search

Web read

Browser automation

Person intelligence

Universal tool method

Get balance

Spend budgets

Error handling

Build production websites

Update existing website

Complete agent example

Next steps

API Reference

SDK Source

Optional phone lookup

​Initialize

​Email

​Bulk email

​Voice calls

​SMS

​Deep research

​Poll inbox

​People search and enrichment

​Find and verify email

​Commerce: search and buy

​Web search

​Web read

​Browser automation

​Person intelligence

​Universal tool method

​Get balance

​Spend budgets

​Error handling

​Build production websites

​Update existing website

​Complete agent example

​Next steps

API Reference

SDK Source

​Optional phone lookup

Initialize

Email

Bulk email

Voice calls

SMS

Deep research

Poll inbox

People search and enrichment

Find and verify email

Commerce: search and buy

Web search

Web read

Browser automation

Person intelligence

Universal tool method

Get balance

Spend budgets

Error handling

Build production websites

Update existing website

Complete agent example

Next steps

Optional phone lookup