Sending Emails

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

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_="[email protected]",
    to=["[email protected]"],
    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: '[email protected]',
  to: ['[email protected]'],
  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: "[email protected]",
  to: ["[email protected]"],
  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:    "[email protected]",
    To:      []string{"[email protected]"},
    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": "[email protected]",
    "to": ["[email protected]"],
    "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_="[email protected]",
    to=["[email protected]", "[email protected]"],
    cc=["[email protected]"],
    bcc=["[email protected]"],
    subject="Team Update",
    html="<p>Here is your weekly update...</p>"
)

const email = await client.emails.send({
  from: '[email protected]',
  to: ['[email protected]', '[email protected]'],
  cc: ['[email protected]'],
  bcc: ['[email protected]'],
  subject: 'Team Update',
  html: '<p>Here is your weekly update...</p>',
});

email = client.emails.send_(
  from: "[email protected]",
  to: ["[email protected]", "[email protected]"],
  cc: ["[email protected]"],
  bcc: ["[email protected]"],
  subject: "Team Update",
  html: "<p>Here is your weekly update...</p>"
)

email, err := client.Emails.Send(ctx, ark.EmailSendParams{
    From:    "[email protected]",
    To:      []string{"[email protected]", "[email protected]"},
    CC:      []string{"[email protected]"},
    BCC:     []string{"[email protected]"},
    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 tags and metadata to categorize and track emails:

Python
Node.js
Ruby
Go

email = client.emails.send(
    from_="[email protected]",
    to=["[email protected]"],
    subject="Order Confirmation #1234",
    html="<p>Thank you for your order!</p>",
    tags=["orders", "confirmation"],
    metadata={
        "order_id": "1234",
        "customer_id": "cust_abc123",
        "order_total": "99.99"
    }
)

const email = await client.emails.send({
  from: '[email protected]',
  to: ['[email protected]'],
  subject: 'Order Confirmation #1234',
  html: '<p>Thank you for your order!</p>',
  tags: ['orders', 'confirmation'],
  metadata: {
    orderId: '1234',
    customerId: 'cust_abc123',
    orderTotal: '99.99',
  },
});

email = client.emails.send_(
  from: "[email protected]",
  to: ["[email protected]"],
  subject: "Order Confirmation #1234",
  html: "<p>Thank you for your order!</p>",
  tags: ["orders", "confirmation"],
  metadata: {
    order_id: "1234",
    customer_id: "cust_abc123",
    order_total: "99.99"
  }
)

email, err := client.Emails.Send(ctx, ark.EmailSendParams{
    From:    "[email protected]",
    To:      []string{"[email protected]"},
    Subject: "Order Confirmation #1234",
    HTML:    ark.String("<p>Thank you for your order!</p>"),
    Tags:    []string{"orders", "confirmation"},
    Metadata: map[string]string{
        "order_id":    "1234",
        "customer_id": "cust_abc123",
        "order_total": "99.99",
    },
})

Tags and metadata are included in webhook events, making it easy to correlate emails with your application data.

Scheduling Emails

Schedule an email to send at a specific time:

Python
Node.js
Ruby
Go

email = client.emails.send(
    from_="[email protected]",
    to=["[email protected]"],
    subject="Your Weekly Digest",
    html="<p>Here is what happened this week...</p>",
    scheduled_at="2024-01-20T09:00:00Z"  # ISO 8601 format
)

const email = await client.emails.send({
  from: '[email protected]',
  to: ['[email protected]'],
  subject: 'Your Weekly Digest',
  html: '<p>Here is what happened this week...</p>',
  scheduledAt: '2024-01-20T09:00:00Z',  // ISO 8601 format
});

email = client.emails.send_(
  from: "[email protected]",
  to: ["[email protected]"],
  subject: "Your Weekly Digest",
  html: "<p>Here is what happened this week...</p>",
  scheduled_at: "2024-01-20T09:00:00Z"  # ISO 8601 format
)

email, err := client.Emails.Send(ctx, ark.EmailSendParams{
    From:        "[email protected]",
    To:          []string{"[email protected]"},
    Subject:     "Your Weekly Digest",
    HTML:        ark.String("<p>Here is what happened this week...</p>"),
    ScheduledAt: ark.String("2024-01-20T09:00:00Z"),
})

Emails can be scheduled up to 7 days in advance.

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_="[email protected]",
    to=["[email protected]"],
    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: '[email protected]',
  to: ['[email protected]'],
  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: "[email protected]",
  to: ["[email protected]"],
  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:    "[email protected]",
    To:      []string{"[email protected]"},
    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_="[email protected]",
    to=["[email protected]"],
    subject="Re: Support Ticket #5678",
    html="<p>Thank you for contacting support...</p>",
    reply_to="[email protected]",
    headers={
        "X-Ticket-ID": "5678",
        "References": "<[email protected]>",
        "In-Reply-To": "<[email protected]>"
    }
)

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

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

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

Controlling Tracking

Disable tracking for sensitive emails:

Python
Node.js
Ruby
Go

email = client.emails.send(
    from_="[email protected]",
    to=["[email protected]"],
    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: '[email protected]',
  to: ['[email protected]'],
  subject: 'Password Reset',
  html: '<p>Click here to reset your password...</p>',
  trackOpens: false,
  trackClicks: false,
});

email = client.emails.send_(
  from: "[email protected]",
  to: ["[email protected]"],
  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:        "[email protected]",
    To:          []string{"[email protected]"},
    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_="[email protected]",
        to=["[email protected]"],
        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: '[email protected]',
    to: ['[email protected]'],
    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: "[email protected]",
    to: ["[email protected]"],
    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 [email protected], use "Your Company" <[email protected]>.

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

Guides

Concepts

Reference

Basic Email

Multiple Recipients

Using Tags and Metadata

Scheduling Emails

Attachments

Custom Headers

Controlling Tracking

Error Handling

Best Practices

Next Steps

Batch Sending

Webhook Integration

Getting Started

Guides

Concepts

Reference

​Basic Email

​Multiple Recipients

​Using Tags and Metadata

​Scheduling Emails

​Attachments

​Custom Headers

​Controlling Tracking

​Error Handling

​Best Practices

​Next Steps

Batch Sending

Webhook Integration

Basic Email

Multiple Recipients

Using Tags and Metadata

Scheduling Emails

Attachments

Custom Headers

Controlling Tracking

Error Handling

Best Practices

Next Steps