Recruiting teams spend hours manually drafting candidate screening emails and scheduling confirmations, slowing hiring timelines and reducing recruiter productivity. AgentMail provides a REST API for AI agents to create, send, and manage real emails, enabling autonomous recruiting workflows to handle candidate communications at scale. By exposing email drafting and sending to your agents via AgentMail's API, you automate repetitive screening messages while maintaining human control before send. Agents can draft candidate responses, search for messages by candidate name or date, and send confirmations—all natively through email without leaving your agentic workflow.
What this tutorial covers
- •Outcome: You will build an autonomous agent that drafts candidate screening emails, updates them based on recruiter feedback, searches message history, and sends interview confirmations via AgentMail.
- •Endpoints used: `POST /v0/inboxes/{inbox_id}/drafts`, `PATCH /v0/inboxes/{inbox_id}/drafts/{draft_id}`, `GET /v0/inboxes/{inbox_id}/messages/search`, `POST /v0/inboxes/{inbox_id}/messages/send`, `POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply`
- •SDK methods: `createDraft(inboxId, subject, body, to)`, `updateDraft(inboxId, draftId, updates)`, `searchMessages(inboxId, query)`, `sendMessage(inboxId, draftId)`
- •Language: typescript
- •Auth: Bearer token in Authorization header
- •Estimated implementation time: ~18 minutes
Step 1: Set up AgentMail authentication and client initialization
Your agent needs authenticated access to AgentMail's inbox API to read, draft, and send emails on behalf of your recruiting account. Initialize the client with your API key and inbox ID to prepare for all subsequent email operations.
Initialize the AgentMail client
1// AgentMail authentication and client initialization
2const apiToken = process.env.API_TOKEN;
3const inboxId = process.env.INBOX_ID;
4
5if (!apiToken || !inboxId) {
6 throw new Error("Missing API_TOKEN or INBOX_ID environment variables");
7}
8
9const headers = {
10 "Authorization": `${apiToken}`,
11 "Content-Type": "application/json"
12};
13
14console.log(`AgentMail client initialized with inbox: ${inboxId}`);Response:
1// AgentMail Authentication and Client Initialization
2const apiToken = process.env.API_TOKEN;
3const apiBaseUrl = "https://api.agentmail.to/v0";
4
5// Helper function to create authenticated headers
6function createHeaders() {
7 return {
8 "Authorization": apiToken,
9 "Content-Type": "application/json"
10 };
11}
12
13// Initialize client by creating an inbox
14const inboxResponse = await fetch(`${apiBaseUrl}/inboxes`, {
15 method: "POST",
16 headers: createHeaders(),
17 body: JSON.stringify({
18 "username": "string",
19 "domain": "string",
20 "display_name": "string",
21 "client_id": "string"
22 })
23});
24
25const inboxData = await inboxResponse.json();
26
27// Response shape for successful inbox creation
28const client = {
29 "pod_id": inboxData.pod_id,
30 "inbox_id": inboxData.inbox_id,
31 "email": inboxData.email,
32 "display_name": inboxData.display_name,
33 "client_id": inboxData.client_id
34};Step 2: Draft candidate screening emails with agent context
Your agent analyzes candidate profiles and uses AgentMail's draft endpoint to compose personalized screening emails without sending them immediately. Drafts remain editable by human recruiters, ensuring compliance with fairness and auditability requirements before dispatch.
Create a screening email draft
A draft email is created in AgentMail with the screening message. The recruiter reviews it in their inbox interface before the agent sends it, maintaining human control over candidate communications.
Step 3: Update drafts based on recruiter feedback and corrections
Recruiters often refine agent-drafted messages for tone or company policy compliance. AgentMail's update endpoint lets your agent modify drafts before sending. This loop keeps the agent and recruiter synchronized while automating repetitive edits.
Modify draft subject and body
Response:
1const res = await fetch("https://api.agentmail.to/v0/inboxes/{inbox_id}/drafts/{draft_id}", {
2 method: "PATCH",
3 headers: {
4 "Authorization": `${process.env.API_TOKEN}`,
5 "Content-Type": "application/json"
6 },
7 body: JSON.stringify({ "reply_to": ["string"], "to": ["string"], "cc": ["string"], "bcc": ["string"], "subject": "string" })
8});
9const data = await res.json();
10// Response shape: { "inbox_id": "string", "draft_id": "string", "client_id": "string", "labels": ["string"], "reply_to": ["string"] }Step 4: Send interview confirmations and search candidate history with AgentMail
Once a recruiter approves the draft, your agent sends it via AgentMail's send endpoint and searches previous messages to track candidate communication history. This ensures your agent has full context before scheduling interviews and can reference past exchanges in follow-up emails.
Send draft and search message history
Step 5: Reply to candidate responses with AgentMail's reply endpoint
When candidates respond to screening emails, your agent uses AgentMail's reply endpoint to send interview scheduling details or next-step instructions. Replies maintain the email thread context, improving candidate experience and message discoverability in your agent's search queries.
Compose and send email reply
Response:
1const res = await fetch("https://api.agentmail.to/v0/inboxes/{inbox_id}/messages/{message_id}/reply", {
2 method: "POST",
3 headers: {
4 "Authorization": `${process.env.API_TOKEN}`,
5 "Content-Type": "application/json"
6 },
7 body: JSON.stringify({ "labels": ["string"], "reply_to": "string", "to": "string", "cc": "string", "bcc": "string" })
8});
9const data = await res.json();
10// Response shape: { "message_id": "string", "thread_id": "string" }Step 6: Maintain governance and auditability in AgentMail-powered recruiting workflows
AI-driven recruitment carries risk of bias and automation bias if agent decisions are not logged and reviewed. AgentMail stores all drafts, sends, and replies with timestamps. Log agent prompts, reasoning, and recruiter approvals alongside AgentMail message IDs to satisfy compliance requirements and defend hiring fairness.
Log agent activity and decisions
Each agent action is logged with timestamps, candidate identifiers, agent reasoning, and recruiter approval IDs. This audit trail satisfies governance requirements and enables post-hoc review of hiring fairness across your AgentMail messaging campaigns.
Common pitfalls when using AgentMail
- •**Automation bias:Over-relying on agent screening without recruiter review. Setting agents to send screening emails without a human-in-the-loop phase risks poor candidate fit decisions. Always have recruiters review and approve AgentMail drafts before send; use PATCH to incorporate feedback before POST /messages/send.
- •Insufficient bias testing in agent prompts. Agent-generated screening emails can inadvertently favor or penalize candidates by demographic group. Audit your agent's prompt engineering, test outputs for fairness by demographic, and document findings in your audit trail before go-live.
- •Losing context in multi-email threads. Candidates often respond to screening emails hours or days later. Use GET /messages/search to retrieve full conversation history before drafting replies; this prevents conflicting or redundant messages that degrade candidate experience.
- •Storing plaintext API keys in code. Never hardcode your AgentMail API key in source files. Use environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault) and rotate keys regularly to prevent unauthorized access to candidate emails.
Ready to automate your recruiting workflow while keeping human control? Deploy this pattern with AgentMail today to cut time-to-hire and scale candidate communications without sacrificing fairness or auditability.
Documentation references
The code examples in this tutorial are grounded in the following docs pages:
- •
Ready to give your agents real email access?
Join leading developers using AgentMail to enable AI agents to send, receive, and search email natively via API.
Read More Blog Posts
Automate order exceptions and supplier escalations with AI agents
Order exceptions like shipment delays and pricing discrepancies require rapid detection and escalation, but manual email coordination slows response. AgentMail
Auto-triage referral emails and draft specialist confirmations
Healthcare teams manually sort incoming referral emails, risking delayed specialist confirmations and patient care gaps. AgentMail enables AI agents to search,