This QuickStart guide is designed to assist you in making your first API call. We recommend using our SDKs, however, you may find it more beneficial to go directly to the API reference documentation.
Prefer AI to build everything for you? Visit app.contacted.io/console/agent to have AI agents like Cursor install and configure your entire email system in under 8 minutes.
If you would like to interact with generating emails before making an API call, please visit the developer playground.
This guide will walk you through:
Setting up your developer environment
Installing the Contacted library
Making your first request to the Contacted API
Understanding advanced data parsing
Prerequisites
To complete this guide, you will need:
Branding setup on account
A Contacted API key
Python 3.7+ or TypeScript 4.5+
1. Setup your API key
The first thing you will need is a valid API key. Please visit this link and navigate to "API Keys" on the left nav bar.
2. Install the Contacted library
Node.js
Python
Note: You can also call the underlying API directly (see our API Docs).
3. Making a request
JavaScript
Python
4. Advanced Data Parsing
You can pass any data that should be included in the email through the data object. Our AI intelligently understands context and weaves this information seamlessly into your emails.
Key Features:
✅ Reference data keys in prompts for custom instructions✅ Include images via URLs✅ Pass any type of data (numbers, dates, arrays, etc.)✅ AI automatically understands data types and context
Important: All data values must be strings. Don't worry about types—our AI will understand the meaning.
Basic Data Example
Advanced Data with Custom Instructions
Including Images
Complex Data Structures
Data Types Our AI Understands
Data Type
Example
How AI Interprets
Names
"John Doe"
Personal identifiers, greetings
Dates
"2025-07-15" or "July 15th"
Scheduling, deadlines, timestamps
Prices
"29.99" or "$29.99"
Financial information, pricing
URLs
"https://example.com"
Links, buttons, references
Images
"https://cdn.example.com/image.jpg"
Visual content placement
Lists
"Item 1, Item 2, Item 3"
Formatted lists, enumerations
Numbers
"42" or "1,234"
Quantities, metrics, counts
Next Steps
Explore the API Playground to test prompts and see live previews
Set up Branding to ensure emails match your company style
const ContactedAI = require("contacted")
const contacted = new ContactedAI({
apiKey: process.env['CONTACTED_API_KEY']
})
const response = await contacted.send({
subject: "Reset Password Notification",
from: "<sender address>",
to: "<receiver address>",
prompt: "Password reset email. Include that it will expire in 20 minutes.",
data: {
"link": "https://example.com/reset?secret=1234565"
}
})
import os
from contacted import ContactedAI
contacted = ContactedAI(
api_key=os.environ.get("CONTACTED_API_KEY")
)
contacted.send(
subject="Reset Password Notification",
from_email="<sender address>",
to_email="<receiver address>",
prompt="Password reset email. Include that it will expire in 20 minutes.",
data={
'link': 'https://example.com/reset?secret=1234565'
}
)
contacted.send(
subject="Welcome to Premium!",
prompt="Welcome email for a new premium subscriber",
data={
"user_name": "Sarah Johnson",
"plan_name": "Premium Plan",
"monthly_cost": "29.99",
"next_billing": "2025-07-15",
"features_count": "50"
}
)
contacted.send(
subject="Your Order is Confirmed!",
prompt="""
Order confirmation email. Use order_number prominently at the top.
List all items from item_list with their quantities.
Show total_amount as the final price.
Include shipping_date as an estimated delivery timeframe.
""",
data={
"order_number": "ORD-2025-1234",
"customer_name": "Alex Chen",
"item_list": "2x Premium T-Shirt, 1x Hoodie, 3x Stickers",
"total_amount": "89.97",
"shipping_date": "June 20, 2025",
"tracking_url": "https://tracking.example.com/ORD-2025-1234"
}
)
contacted.send(
subject="Your Monthly Report",
prompt="""
Monthly report email. Use cover_image as a hero image at the top.
Include chart_image in the metrics section to show performance data.
Use profile_photo next to the user's name in the greeting.
""",
data={
"user_name": "Jordan Smith",
"report_month": "May 2025",
"cover_image": "https://example.com/images/monthly-report-cover.jpg",
"chart_image": "https://example.com/charts/may-2025-metrics.png",
"profile_photo": "https://example.com/profiles/jordan-smith.jpg",
"key_metric": "127% growth",
"report_url": "https://dashboard.example.com/reports/may-2025"
}
)
contacted.send(
subject="Event Invitation",
prompt="""
Event invitation email. Use event_banner as the main header image.
List all speakers from speaker_list with their titles.
Include agenda_items as a schedule section.
Show ticket_price and registration_link prominently.
""",
data={
"event_name": "DevCon 2025",
"event_date": "July 15-16, 2025",
"event_banner": "https://example.com/events/devcon-2025-banner.jpg",
"speaker_list": "Sarah Kim (CTO, TechCorp), Mike Johnson (Lead Developer, StartupXYZ), Lisa Wang (Product Manager, BigTech)",
"agenda_items": "Day 1: AI in Development, API Best Practices, Scaling Microservices. Day 2: DevOps Workshop, Security Panel, Networking Session",
"venue": "San Francisco Convention Center",
"ticket_price": "299",
"early_bird_price": "199",
"registration_link": "https://events.example.com/devcon2025/register"
}
)
