This guide walks you through sending your first email with Ark. You’ll set up your sending domain and send a test email.
$2.50 Welcome Credit: All new organizations receive $2.50 in free credits - enough to send ~5,000 emails. Learn more about billing. 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
You have two options to send your first email:
No domain setup required! Use sandbox mode to test immediately. Send from [email protected] to any organization member.Sandbox Restrictions: Recipients must be members of your Ark organization. Add team members at arkhq.io/org/team. Limited to 10 emails/day. For production use, configure a sending domain at arkhq.io/org/domains. Follow the DNS configuration instructions to verify your domain. See our domain setup guide for detailed instructions. Step 4: Send the Email
Send a test email. For sandbox mode, use [email protected] as the sender and a team member’s email as recipient. For production, use your verified domain:
Python
Node.js
Ruby
Go
cURL
import os
from ark import Ark
client = Ark(api_key=os.environ.get("ARK_API_KEY"))
# Sandbox mode: use [email protected], send to a team member
# Production: use your verified domain
email = client.emails.send(
from_="[email protected]", # or "[email protected]" for production
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}")
# Sandbox emails include: email.data.sandbox == True
import Ark from 'ark-email';
const client = new Ark({
apiKey: process.env.ARK_API_KEY,
});
// Sandbox mode: use [email protected], send to a team member
// Production: use your verified domain
const email = await client.emails.send({
from: '[email protected]', // or '[email protected]' for production
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}`);
// Sandbox emails include: email.data.sandbox === true
require "ark_email"
client = ArkEmail::Client.new(api_key: ENV["ARK_API_KEY"])
# Sandbox mode: use [email protected], send to a team member
# Production: use your verified domain
email = client.emails.send_(
from: "[email protected]", # or "[email protected]" for production
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}"
# Sandbox emails include: email.data.sandbox == true
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
// Sandbox mode: use [email protected], send to a team member
// Production: use your verified domain
email, err := client.Emails.Send(context.Background(), ark.EmailSendParams{
From: "[email protected]", // or "[email protected]" for production
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)
// Sandbox emails include: email.Data.Sandbox == true
}
# Sandbox mode: use [email protected], send to a team member
# Production: use your verified domain
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]"],
"sandbox": true // Only present for sandbox emails
},
"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.
Sandbox Response: The sandbox: true field in the response indicates the email was sent via sandbox mode. Sandbox emails don’t incur billing charges.
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 sandbox or custom domain)
- Verified delivery status
Next Steps
