Sending Emails — Patterns & Best Practices

This guide covers common patterns for sending transactional emails with Ark, from simple notifications to complex templates.

Building a white-label platform? You can send emails scoped to specific tenants using tenant_id. See the Architecture Overview for white-label sending patterns.

Basic Email

Send a simple email with HTML and plain text:

Python
Node.js
Ruby
Go
cURL

from ark import Ark

client = Ark()

email = client.emails.send(
    from_="hello@yourdomain.com",
    to=["user@example.com"],
    subject="Your order has shipped!",
    html="<h1>Order Shipped</h1><p>Your order #1234 is on its way.</p>",
    text="Order Shipped\n\nYour order #1234 is on its way."
)

print(f"Email sent: {email.data.id}")

import Ark from 'ark';

const client = new Ark();

const email = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Your order has shipped!',
  html: '<h1>Order Shipped</h1><p>Your order #1234 is on its way.</p>',
  text: 'Order Shipped\n\nYour order #1234 is on its way.',
});

console.log(`Email sent: ${email.data.id}`);

require "ark_email"

client = ArkEmail::Client.new

email = client.emails.send_(
  from: "hello@yourdomain.com",
  to: ["user@example.com"],
  subject: "Your order has shipped!",
  html: "<h1>Order Shipped</h1><p>Your order #1234 is on its way.</p>",
  text: "Order Shipped\n\nYour order #1234 is on its way."
)

puts "Email sent: #{email.data.id}"

client := ark.NewClient()

email, err := client.Emails.Send(ctx, ark.EmailSendParams{
    From:    "hello@yourdomain.com",
    To:      []string{"user@example.com"},
    Subject: "Your order has shipped!",
    HTML:    ark.String("<h1>Order Shipped</h1><p>Your order #1234 is on its way.</p>"),
    Text:    ark.String("Order Shipped\n\nYour order #1234 is on its way."),
})

curl -X POST https://api.arkhq.io/v1/emails \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Your order has shipped!",
    "html": "<h1>Order Shipped</h1><p>Your order #1234 is on its way.</p>",
    "text": "Order Shipped\n\nYour order #1234 is on its way."
  }'

Always include both html and text versions. Some email clients only display plain text, and it improves deliverability.

Multiple Recipients

Send to multiple recipients in a single request:

Python
Node.js
Ruby
Go

email = client.emails.send(
    from_="team@yourdomain.com",
    to=["user1@example.com", "user2@example.com"],
    cc=["manager@example.com"],
    bcc=["archive@yourdomain.com"],
    subject="Team Update",
    html="<p>Here is your weekly update...</p>"
)

const email = await client.emails.send({
  from: 'team@yourdomain.com',
  to: ['user1@example.com', 'user2@example.com'],
  cc: ['manager@example.com'],
  bcc: ['archive@yourdomain.com'],
  subject: 'Team Update',
  html: '<p>Here is your weekly update...</p>',
});

email = client.emails.send_(
  from: "team@yourdomain.com",
  to: ["user1@example.com", "user2@example.com"],
  cc: ["manager@example.com"],
  bcc: ["archive@yourdomain.com"],
  subject: "Team Update",
  html: "<p>Here is your weekly update...</p>"
)

email, err := client.Emails.Send(ctx, ark.EmailSendParams{
    From:    "team@yourdomain.com",
    To:      []string{"user1@example.com", "user2@example.com"},
    CC:      []string{"manager@example.com"},
    BCC:     []string{"archive@yourdomain.com"},
    Subject: "Team Update",
    HTML:    ark.String("<p>Here is your weekly update...</p>"),
})

Maximum 50 recipients per request. For larger sends, use the batch endpoint or make multiple requests.

Using Tags and Metadata

Add a tag and metadata to categorize and track emails:

Python
Node.js
Ruby
Go

email = client.emails.send(
    from_="orders@yourdomain.com",
    to=["customer@example.com"],
    subject="Order Confirmation #1234",
    html="<p>Thank you for your order!</p>",
    tag="order_confirmation",
    metadata={
        "order_id": "ord_1234",
        "customer_id": "cust_abc123",
        "campaign": "checkout_flow"
    }
)

const email = await client.emails.send({
  from: 'orders@yourdomain.com',
  to: ['customer@example.com'],
  subject: 'Order Confirmation #1234',
  html: '<p>Thank you for your order!</p>',
  tag: 'order_confirmation',
  metadata: {
    order_id: 'ord_1234',
    customer_id: 'cust_abc123',
    campaign: 'checkout_flow',
  },
});

email = client.emails.send_(
  from: "orders@yourdomain.com",
  to: ["customer@example.com"],
  subject: "Order Confirmation #1234",
  html: "<p>Thank you for your order!</p>",
  tag: "order_confirmation",
  metadata: {
    order_id: "ord_1234",
    customer_id: "cust_abc123",
    campaign: "checkout_flow"
  }
)

email, err := client.Emails.Send(ctx, ark.EmailSendParams{
    From:    "orders@yourdomain.com",
    To:      []string{"customer@example.com"},
    Subject: "Order Confirmation #1234",
    HTML:    ark.String("<p>Thank you for your order!</p>"),
    Tag:     ark.String("order_confirmation"),
    Metadata: map[string]string{
        "order_id":    "ord_1234",
        "customer_id": "cust_abc123",
        "campaign":    "checkout_flow",
    },
})

Metadata in Webhooks: When you include metadata with an email, it’s automatically returned in all webhook events for that message (MessageSent, MessageBounced, etc.). This makes it easy to correlate delivery events with your internal systems.

Metadata Validation Rules

Rule	Limit
Maximum keys	10
Key length	40 characters
Value length	500 characters
Total size	4KB
Key format	Must start with a letter, alphanumeric and underscores only

Metadata keys must match the pattern ^[a-zA-Z][a-zA-Z0-9_]*$. Keys like order-id (hyphen) or 123_key (starts with number) are invalid.

Attachments

Send files as attachments:

Python
Node.js
Ruby
Go

import base64

with open("invoice.pdf", "rb") as f:
    pdf_content = base64.b64encode(f.read()).decode()

email = client.emails.send(
    from_="billing@yourdomain.com",
    to=["customer@example.com"],
    subject="Your Invoice #INV-001",
    html="<p>Please find your invoice attached.</p>",
    attachments=[
        {
            "filename": "invoice.pdf",
            "content": pdf_content,
            "content_type": "application/pdf"
        }
    ]
)

import fs from 'fs';

const pdfBuffer = fs.readFileSync('invoice.pdf');

const email = await client.emails.send({
  from: 'billing@yourdomain.com',
  to: ['customer@example.com'],
  subject: 'Your Invoice #INV-001',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    {
      filename: 'invoice.pdf',
      content: pdfBuffer.toString('base64'),
      contentType: 'application/pdf',
    },
  ],
});

require "base64"

pdf_content = Base64.strict_encode64(File.read("invoice.pdf"))

email = client.emails.send_(
  from: "billing@yourdomain.com",
  to: ["customer@example.com"],
  subject: "Your Invoice #INV-001",
  html: "<p>Please find your invoice attached.</p>",
  attachments: [
    {
      filename: "invoice.pdf",
      content: pdf_content,
      content_type: "application/pdf"
    }
  ]
)

import (
    "encoding/base64"
    "os"
)

pdfData, _ := os.ReadFile("invoice.pdf")
pdfContent := base64.StdEncoding.EncodeToString(pdfData)

email, err := client.Emails.Send(ctx, ark.EmailSendParams{
    From:    "billing@yourdomain.com",
    To:      []string{"customer@example.com"},
    Subject: "Your Invoice #INV-001",
    HTML:    ark.String("<p>Please find your invoice attached.</p>"),
    Attachments: []ark.Attachment{
        {
            Filename:    ark.String("invoice.pdf"),
            Content:     ark.String(pdfContent),
            ContentType: ark.String("application/pdf"),
        },
    },
})

Maximum attachment size is 25MB total. Large attachments may impact deliverability.

Custom Headers

Add custom email headers:

Python
Node.js
Ruby
Go

email = client.emails.send(
    from_="support@yourdomain.com",
    to=["customer@example.com"],
    subject="Re: Support Ticket #5678",
    html="<p>Thank you for contacting support...</p>",
    reply_to="support+5678@yourdomain.com",
    headers={
        "X-Ticket-ID": "5678",
        "References": "<original-message-id@example.com>",
        "In-Reply-To": "<original-message-id@example.com>"
    }
)

const email = await client.emails.send({
  from: 'support@yourdomain.com',
  to: ['customer@example.com'],
  subject: 'Re: Support Ticket #5678',
  html: '<p>Thank you for contacting support...</p>',
  replyTo: 'support+5678@yourdomain.com',
  headers: {
    'X-Ticket-ID': '5678',
    'References': '<original-message-id@example.com>',
    'In-Reply-To': '<original-message-id@example.com>',
  },
});

email = client.emails.send_(
  from: "support@yourdomain.com",
  to: ["customer@example.com"],
  subject: "Re: Support Ticket #5678",
  html: "<p>Thank you for contacting support...</p>",
  reply_to: "support+5678@yourdomain.com",
  headers: {
    "X-Ticket-ID" => "5678",
    "References" => "<original-message-id@example.com>",
    "In-Reply-To" => "<original-message-id@example.com>"
  }
)

email, err := client.Emails.Send(ctx, ark.EmailSendParams{
    From:    "support@yourdomain.com",
    To:      []string{"customer@example.com"},
    Subject: "Re: Support Ticket #5678",
    HTML:    ark.String("<p>Thank you for contacting support...</p>"),
    ReplyTo: ark.String("support+5678@yourdomain.com"),
    Headers: map[string]string{
        "X-Ticket-ID": "5678",
        "References":  "<original-message-id@example.com>",
        "In-Reply-To": "<original-message-id@example.com>",
    },
})

Controlling Tracking

Disable tracking for sensitive emails:

Python
Node.js
Ruby
Go

email = client.emails.send(
    from_="security@yourdomain.com",
    to=["user@example.com"],
    subject="Password Reset",
    html="<p>Click here to reset your password...</p>",
    track_opens=False,
    track_clicks=False
)

const email = await client.emails.send({
  from: 'security@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Password Reset',
  html: '<p>Click here to reset your password...</p>',
  trackOpens: false,
  trackClicks: false,
});

email = client.emails.send_(
  from: "security@yourdomain.com",
  to: ["user@example.com"],
  subject: "Password Reset",
  html: "<p>Click here to reset your password...</p>",
  track_opens: false,
  track_clicks: false
)

email, err := client.Emails.Send(ctx, ark.EmailSendParams{
    From:        "security@yourdomain.com",
    To:          []string{"user@example.com"},
    Subject:     "Password Reset",
    HTML:        ark.String("<p>Click here to reset your password...</p>"),
    TrackOpens:  ark.Bool(false),
    TrackClicks: ark.Bool(false),
})

Error Handling

All SDKs provide typed exceptions for error handling:

Python
Node.js
Ruby
Go

import ark

try:
    email = client.emails.send(
        from_="hello@yourdomain.com",
        to=["user@example.com"],
        subject="Test",
        html="<p>Test</p>"
    )
    print(f"Email accepted: {email.data.id}")
except ark.BadRequestError as e:
    print(f"Invalid request: {e.message}")
except ark.RateLimitError as e:
    print(f"Rate limited - retry later")
except ark.APIError as e:
    print(f"API error: {e.message}")

import Ark from 'ark';

try {
  const email = await client.emails.send({
    from: 'hello@yourdomain.com',
    to: ['user@example.com'],
    subject: 'Test',
    html: '<p>Test</p>',
  });
  console.log(`Email accepted: ${email.data.id}`);
} catch (error) {
  if (error instanceof Ark.BadRequestError) {
    console.log(`Invalid request: ${error.message}`);
  } else if (error instanceof Ark.RateLimitError) {
    console.log('Rate limited - retry later');
  } else if (error instanceof Ark.APIError) {
    console.log(`API error: ${error.message}`);
  }
}

begin
  email = client.emails.send_(
    from: "hello@yourdomain.com",
    to: ["user@example.com"],
    subject: "Test",
    html: "<p>Test</p>"
  )
  puts "Email accepted: #{email.data.id}"
rescue ArkEmail::Errors::BadRequestError => e
  puts "Invalid request: #{e.message}"
rescue ArkEmail::Errors::RateLimitError => e
  puts "Rate limited - retry later"
rescue ArkEmail::Errors::APIError => e
  puts "API error: #{e.message}"
end

import "errors"

email, err := client.Emails.Send(ctx, params)
if err != nil {
    var arkErr *ark.Error
    if errors.As(err, &arkErr) {
        switch arkErr.StatusCode {
        case 400:
            fmt.Printf("Invalid request: %s\n", arkErr.Message)
        case 429:
            fmt.Println("Rate limited - retry later")
        default:
            fmt.Printf("API error: %s\n", arkErr.Message)
        }
    }
    return
}
fmt.Printf("Email accepted: %s\n", email.Data.ID)

Best Practices

Always include plain text

Some email clients and spam filters prefer or require plain text versions.

Use descriptive from names

Instead of just noreply@yourdomain.com, use "Your Company" <noreply@yourdomain.com>.

Keep subjects under 50 characters

Longer subjects get truncated on mobile devices.

Test before sending

Send test emails to yourself to verify formatting across different clients.

Handle bounces

Set up webhooks to receive bounce notifications and update your recipient list.

Next Steps

Batch Sending

Send multiple emails efficiently

Webhook Integration

Track delivery and engagement

Getting Started

White-Label Email Architecture

Sending Email

Domain Setup

Webhooks

Tracking & Deliverability

Concepts

Migration

Reference

Sending Emails — Patterns & Best Practices

Basic Email

Multiple Recipients

Using Tags and Metadata

Metadata Validation Rules

Attachments

Custom Headers

Controlling Tracking

Error Handling

Best Practices

Next Steps

Batch Sending

Webhook Integration

Getting Started

White-Label Email Architecture

Sending Email

Domain Setup

Webhooks

Tracking & Deliverability

Concepts

Migration

Reference

​Basic Email

​Multiple Recipients

​Using Tags and Metadata

​Metadata Validation Rules

​Attachments

​Custom Headers

​Controlling Tracking

​Error Handling

​Best Practices

​Next Steps

Batch Sending

Webhook Integration

Basic Email

Multiple Recipients

Using Tags and Metadata

Metadata Validation Rules

Attachments

Custom Headers

Controlling Tracking

Error Handling

Best Practices

Next Steps