Quickstart

Get started with the Contacted API.

QuickStart Guide

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.

export CONTACTED_API_KEY="your-api-key-here"

2. Install the Contacted library

Node.js

npm install contacted

Python

pip install contacted

Note: You can also call the underlying API directly (see our API Docs).

3. Making a request

JavaScript

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"
    }
})

Python

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'
    }
)

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

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"
    }
)

Advanced Data with Custom Instructions

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"
    }
)

Including Images

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"
    }
)

Complex Data Structures

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"
    }
)

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

Ready to send more advanced emails? Our AI handles the complexity—you just describe what you need!

PreviousOverviewNextExamples

Last updated