Contacted TypeScript and JavaScript API Library

Official Node.js SDK for the Contacted API.

Get Your API Key

First, sign up and get your API key at https://contacted.io

Installation

npm install contacted

Quick Start

constContactedAI=require('contacted');constcontacted=newContactedAI({apiKey: 'your-api-key-here'});// Send a messageconstresult=awaitcontacted.send({subject: 'Thank you for signing up with us.',from: 'sender@example.com',to: 'receiver@example.com',prompt: 'Generate a personalized welcome email',data: {name: 'John Doe',link: 'https://example.com'}});console.log('Message sent:',result);// Check message statusconststatus=awaitcontacted.getMessageStatus(result.id);console.log('Message status:',status.status);

TypeScript Support

importContactedAI,{SendOptions}from'contacted';constcontacted=newContactedAI({apiKey: process.env.CONTACTED_API_KEY});constoptions: SendOptions={subject: 'Email subject line',from: 'sender@example.com',to: 'receiver@example.com',prompt: 'Generate email content',data: {name: 'John'}};awaitcontacted.send(options);

API Reference

new ContactedAI(options)

Creates a new ContactedAI client instance.

Parameters:

• apiKey (string, required): Your ContactedAI API key
• baseURL (string, optional): Custom API base URL
• timeout (number, optional): Request timeout in milliseconds (default: 30000)

contacted.send(options)

Send a message through the ContactedAI API.

Parameters:

• subject (string, required): Email subject (2-256 characters)
• from (string, required): Valid sender email address
• to (string, required): Valid receiver email address
• prompt (string, required): AI prompt (10-2000 characters)
• data (object, optional): Additional data for personalization

Validation Rules:

• Subject must be 2-256 characters
• Email addresses must be valid format
• Prompt must be 10-2000 characters
• Data keys cannot contain spaces
• Data keys must be non-empty strings

Returns:Promise<SendResponse>

contacted.getMessageStatus(messageId)

Get the status of a sent message.

Parameters:

• messageId (string, required): The unique message ID returned from send()

Returns:Promise<MessageStatusResponse> - Message status information containing:

• id (string): Message ID
• status (string): Current status (queued, sent, failed)
• message (string): Human-readable status message
• created_at (string): Message creation timestamp
• updated_at (string): Last status update timestamp
• sent_at (string, optional): Delivery timestamp (when status is 'sent')
• error_reason (string, optional): Error description (when status is 'failed')

Throws:Error - If messageId is invalid or API error occurs

contacted.status()

Check the API status and health.

Returns:Promise<StatusResponse>

Error Handling

The SDK provides detailed error messages for validation and API errors:

try{awaitcontacted.send({subejct: 'test error',from: 'invalid-email',to: 'user@example.com',prompt: 'short'});}catch(error){console.error('Error:',error.message);// "Invalid 'from' email address format"}

Examples

Basic Usage

constcontacted=newContactedAI({apiKey: process.env.CONTACTED_API_KEY});constresult=awaitcontacted.send({subject: 'A warm welcome from my service',from: 'noreply@myapp.com',to: 'user@example.com',prompt: 'Create a welcome email for a new premium user',data: {username: 'john_doe',plan: 'premium',dashboardUrl: 'https://app.myservice.com'}});

Send and Track Message Status

constContactedAI=require('contacted');constcontacted=newContactedAI({apiKey: 'your-api-key-here'});// Send messageconstresult=awaitcontacted.send({subject: 'Your order confirmation',from: 'orders@mystore.com',to: 'customer@example.com',prompt: 'Generate an order confirmation email',data: {orderId: '12345',total: '$99.99',deliveryDate: '2024-01-20'}});constmessageId=result.id;console.log(`✅ Message queued with ID: ${messageId}`);// Check statusletstatus=awaitcontacted.getMessageStatus(messageId);console.log(`📧 Status: ${status.status} - ${status.message}`);// Poll for completion (optional)while(status.status==='queued'){awaitnewPromise(resolve=>setTimeout(resolve,2000));// Wait 2 secondsstatus=awaitcontacted.getMessageStatus(messageId);console.log(`📧 Status: ${status.status}`);}if(status.status==='sent'){console.log(`✅ Message delivered at ${status.sent_at}`);}elseif(status.status==='failed'){console.log(`❌ Message failed: ${status.error_reason}`);}

With Error Handling

try{constresult=awaitcontacted.send(options);console.log('✅ Email sent successfully:',result.id);// Check statusconststatus=awaitcontacted.getMessageStatus(result.id);console.log(`📧 Current status: ${status.status}`);}catch(error){if(error.message.includes('Invalid')){console.error('❌ Validation error:',error.message);}elseif(error.message.includes('not found')){console.error('❌ Message not found:',error.message);}else{console.error('❌ API error:',error.message);}}

Using async/await with TypeScript

importContactedAI,{SendResponse,MessageStatusResponse}from'contacted';constcontacted=newContactedAI({apiKey: process.env.CONTACTED_API_KEY!});asyncfunctionsendAndTrack(): Promise<void>{try{constresult: SendResponse=awaitcontacted.send({subject: 'Welcome aboard!',from: 'welcome@myapp.com',to: 'user@example.com',prompt: 'Create a friendly welcome message',data: {firstName: 'Sarah'}});conststatus: MessageStatusResponse=awaitcontacted.getMessageStatus(result.id);console.log(`Message ${result.id} is ${status.status}`);}catch(error){console.error('Operation failed:',error);}}

License

MIT

Support

• 📧 Email: support@contacted.io
• 🐛 Issues: GitHub Issues
• 📖 Documentation: contacted.gitbook.io