This guide walks you through sending your first email with Ark. We’ll use the sandbox domain so you can test immediately without any DNS configuration.
Sandbox Mode: The sandbox domain sandbox.arkhq.io lets you send test emails instantly. For production, you’ll configure your own domain later.
Prerequisites
- An Ark account (sign up free)
- An API key from your dashboard
Step 1: Install the SDK
Python 3.9+ required. For async support: pip install ark-email[aiohttp] Node.js 18+ required. Works with yarn, pnpm, and bun too. Ruby 3.2+ required. Or add gem "ark-email" to your Gemfile. go get github.com/ArkHQ-io/ark-go
Step 2: Get Your API Key
Set environment variable
export ARK_API_KEY="your-api-key-here"
Verification: Run echo $ARK_API_KEY to confirm your key is set. You should see your API key printed.
Step 3: Send Your First Email
Send a test email using the sandbox domain. Replace [email protected] with your actual email address to receive the test:
Python
Node.js
Ruby
Go
cURL
import os
from ark import Ark
client = Ark(api_key=os.environ.get("ARK_API_KEY"))
email = client.emails.send(
from_="[email protected]",
to=["[email protected]"],
subject="Hello from Ark!",
html="<h1>It works!</h1><p>You just sent your first email with Ark.</p>",
text="It works! You just sent your first email with Ark."
)
print(f"Email ID: {email.data.id}")
print(f"Status: {email.data.status}")
import Ark from 'ark-email';
const client = new Ark({
apiKey: process.env.ARK_API_KEY,
});
const email = await client.emails.send({
from: '[email protected]',
to: ['[email protected]'],
subject: 'Hello from Ark!',
html: '<h1>It works!</h1><p>You just sent your first email with Ark.</p>',
text: 'It works! You just sent your first email with Ark.',
});
console.log(`Email ID: ${email.data.id}`);
console.log(`Status: ${email.data.status}`);
require "ark_email"
client = ArkEmail::Client.new(api_key: ENV["ARK_API_KEY"])
email = client.emails.send_(
from: "[email protected]",
to: ["[email protected]"],
subject: "Hello from Ark!",
html: "<h1>It works!</h1><p>You just sent your first email with Ark.</p>",
text: "It works! You just sent your first email with Ark."
)
puts "Email ID: #{email.data.id}"
puts "Status: #{email.data.status}"
Ruby uses send_ (with underscore) because send is a reserved method.
package main
import (
"context"
"fmt"
"log"
"github.com/ArkHQ-io/ark-go"
)
func main() {
client := ark.NewClient() // Uses ARK_API_KEY env var
email, err := client.Emails.Send(context.Background(), ark.EmailSendParams{
From: "[email protected]",
To: []string{"[email protected]"},
Subject: "Hello from Ark!",
HTML: ark.String("<h1>It works!</h1><p>You just sent your first email with Ark.</p>"),
Text: ark.String("It works! You just sent your first email with Ark."),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Email ID: %s\n", email.Data.ID)
fmt.Printf("Status: %s\n", email.Data.Status)
}
curl -X POST https://api.arkhq.io/v1/emails \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Hello from Ark!",
"html": "<h1>It works!</h1><p>You just sent your first email with Ark.</p>",
"text": "It works! You just sent your first email with Ark."
}'
Expected Response
{
"success": true,
"data": {
"id": "msg_abc123xyz",
"status": "pending",
"to": ["[email protected]"]
},
"meta": {
"requestId": "req_def456"
}
}
Verification: Check your inbox for the email. It should arrive within seconds. Also check your spam folder if you don’t see it.
Step 4: Check Email Status
Use the email ID from the response to check delivery status:
Python
Node.js
Ruby
Go
cURL
email = client.emails.retrieve("msg_abc123xyz")
print(f"Status: {email.data.status}")
print(f"Timestamp: {email.data.timestamp_iso}")
const email = await client.emails.retrieve('msg_abc123xyz');
console.log(`Status: ${email.data.status}`);
console.log(`Timestamp: ${email.data.timestampIso}`);
email = client.emails.retrieve("msg_abc123xyz")
puts "Status: #{email.data.status}"
puts "Timestamp: #{email.data.timestamp_iso}"
email, err := client.Emails.Get(ctx, "msg_abc123xyz")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Status: %s\n", email.Data.Status)
fmt.Printf("Timestamp: %s\n", email.Data.TimestampIso)
curl https://api.arkhq.io/v1/emails/msg_abc123xyz \
-H "Authorization: Bearer $ARK_API_KEY"
Status Values
| Status | Description |
|---|
pending | Email accepted, waiting to be processed |
sent | Email transmitted to recipient’s mail server |
softfail | Temporary delivery failure, will retry |
hardfail | Permanent delivery failure |
bounced | Email bounced back |
held | Held for manual review |
Verification: The status should show sent after a few seconds. If it shows bounced, double-check the recipient email address.
You’re All Set!
You’ve successfully:
- Installed the Ark SDK
- Set up your API key
- Sent your first email via the sandbox
- Verified delivery status
Next Steps
Sandbox Limitations: The sandbox domain is for testing only. Emails may be rate-limited and marked as test messages. For production use, configure your own domain. 