Email Lifecycle — From Send to Delivery

import Ark from 'ark';

const client = new Ark();

async function waitForFinalStatus(emailId: string, maxWaitMs = 30000) {
  const startTime = Date.now();
  const terminalStatuses = ['sent', 'hardfail', 'bounced', 'held'];

  while (Date.now() - startTime < maxWaitMs) {
    const email = await client.emails.retrieve(emailId);
    const status = email.data.status;

    if (terminalStatuses.includes(status)) {
      return email.data;
    }

    await new Promise(resolve => setTimeout(resolve, 1000));
  }

  throw new Error('Timeout waiting for final status');
}

// Usage
const result = await waitForFinalStatus('msg_abc123');
console.log(`Final status: ${result.status}`);

require "ark_email"

client = ArkEmail::Client.new

def wait_for_final_status(email_id, max_wait_seconds: 30)
  start_time = Time.now
  terminal_statuses = %w[sent hardfail bounced held]

  while Time.now - start_time < max_wait_seconds
    email = client.emails.retrieve(email_id)
    status = email.data.status

    return email.data if terminal_statuses.include?(status)

    sleep(1)
  end

  raise "Timeout waiting for final status"
end

# Usage
result = wait_for_final_status("msg_abc123")
puts "Final status: #{result.status}"

import (
    "context"
    "errors"
    "time"

    "github.com/ArkHQ-io/ark-go"
)

func waitForFinalStatus(ctx context.Context, client *ark.Client, emailID string, maxWait time.Duration) (*ark.Email, error) {
    deadline := time.Now().Add(maxWait)

    for time.Now().Before(deadline) {
        email, err := client.Emails.Get(ctx, emailID)
        if err != nil {
            return nil, err
        }

        status := email.Data.Status
        if status == "sent" || status == "hardfail" || status == "bounced" || status == "held" {
            return email.Data, nil
        }

        time.Sleep(time.Second)
    }

    return nil, errors.New("timeout waiting for final status")
}

// Usage
result, _ := waitForFinalStatus(ctx, client, "msg_abc123", 30*time.Second)
fmt.Printf("Final status: %s\n", result.Status)

app.post('/webhooks/ark', async (req, res) => {
  const event = req.body;

  switch (event.event) {
    case 'MessageSent':
      console.log(`Email ${event.payload.message.token} sent`);
      await updateEmailStatus(event.payload.message.token, 'sent');
      break;

    case 'MessageBounced':
      console.log(`Email bounced: ${JSON.stringify(event.payload)}`);
      await handleBounce(event.payload);
      break;

    case 'MessageDelayed':
      console.log('Email delayed, will retry');
      break;

    case 'MessageDeliveryFailed':
      console.log('Email delivery failed');
      break;
  }

  res.status(200).send('OK');
});

post '/webhooks/ark' do
  event = JSON.parse(request.body.read)

  case event['event']
  when 'MessageSent'
    puts "Email #{event['payload']['message']['token']} sent"
    update_email_status(event['payload']['message']['token'], 'sent')

  when 'MessageBounced'
    puts "Email bounced: #{event['payload']}"
    handle_bounce(event['payload'])

  when 'MessageDelayed'
    puts 'Email delayed, will retry'

  when 'MessageDeliveryFailed'
    puts 'Email delivery failed'
  end

  'OK'
end

const deliveries = await client.emails.deliveries('msg_abc123');

for (const delivery of deliveries.data) {
  console.log(`${delivery.status}: ${delivery.timestamp}`);
}

deliveries = client.emails.deliveries("msg_abc123")

deliveries.data.each do |delivery|
  puts "#{delivery.status}: #{delivery.timestamp}"
end

deliveries, _ := client.Emails.Deliveries(ctx, "msg_abc123")

for _, delivery := range deliveries.Data {
    fmt.Printf("%s: %s\n", delivery.Status, delivery.Timestamp)
}

curl "https://api.arkhq.io/v1/emails/msg_abc123/deliveries" \
  -H "Authorization: Bearer $ARK_API_KEY"