blastengineのGo SDKを使ってメール配信ログを取得する

[blastengine（ブラストエンジン）](https://blastengine.jp/)はシンプルに使える開発者向けメールサービスを提供しています。何かと面倒なメール配信をシンプルに、かつ確実に送信先へメールを届けられます。

今回は、現在開発しているGo SDKについて、メール配信後に利用できる「配信ログの取得」について解説します。

## メール配信ログとは

メール配信ログは、送信したメールの配信状況を追跡するための重要な情報です。blastengineでは、各メールの配信状態、配信時間、開封時間、エラー情報などを詳細に記録しています。これらのログを活用することで、以下のようなことが可能になります：

- 配信の成功率の確認
- エラーが発生したメールの特定と原因分析
- ユーザーのメール開封状況の把握
- 配信パフォーマンスの分析と改善

## MailLog構造体

blastengine-goでは、`MailLog`構造体を使ってメール配信ログを表現しています。この構造体には以下のフィールドが含まれています：

```go
type MailLog struct {
	Client *Client

	DeliveryTime        time.Time        `json:"delivery_time"`
	DeliveryId          int              `json:"delivery_id"`
	MaillogId           int              `json:"maillog_id"`
	DeliveryType        string           `json:"delivery_type"`
	Email               string           `json:"email"`
	Status              string           `json:"status"`
	LastResponseCode    string           `json:"last_response_code"`
	LastResponseMessage string           `json:"last_response_message"`
	OpenTime            time.Time        `json:"open_time"`
	CreatedTime         time.Time        `json:"created_time"`
	UpdatedTime         time.Time        `json:"updated_time"`
	SentHistories       []MailLogHistory `json:"sent_history"`
}
```

また、各メールの送信履歴を表す`MailLogHistory`構造体も提供されています：

```go
type MailLogHistory struct {
	Client          *Client
	Status          string    `json:"status"`
	DeliveryTime    time.Time `json:"delivery_time"`
	ResponseCode    int       `json:"response_code"`
	ResponseMessage string    `json:"response_message"`
}
```

## ログ取得のためのパラメータ

メール配信ログを取得する際には、様々な条件でフィルタリングすることができます。`GetLogsParams`構造体を使って、これらの条件を指定します：

```go
type GetLogsParams struct {
	Anchor        int       `url:"anchor"`
	Count         int       `url:"count"`
	Email         string    `url:"email"`
	DeliveryType  []string  `url:"delivery_type[]"`
	DeliveryId    int       `url:"delivery_id"`
	Status        []string  `url:"status[]"`
	ResponseCode  []string  `url:"response_code[]"`
	DeliveryStart time.Time `url:"delivery_start"`
	DeliveryEnd   time.Time `url:"delivery_end"`
}
```

各パラメータの意味は以下の通りです：

- `Anchor`: ページネーションのためのアンカー（特定のログID）
- `Count`: 取得するログの最大数
- `Email`: 特定のメールアドレスでフィルタリング
- `DeliveryType`: 配信タイプでフィルタリング（"BULK"や"TRANSACTION"など）
- `DeliveryId`: 特定の配信IDでフィルタリング
- `Status`: ステータスでフィルタリング（"SENT"や"SOFTERROR"など）
- `ResponseCode`: レスポンスコードでフィルタリング（"250"や"550"など）
- `DeliveryStart`: 配信開始日時
- `DeliveryEnd`: 配信終了日時

## メール配信ログの取得方法

### 初期化

まず、APIキーとユーザIDを使ってクライアントを初期化します：

```go
package main

import (
	"fmt"
	"github.com/blastengineMania/blastengine-go"
)

func main() {
	apiKey := "yourApiKey"
	userId := "yourUserId"
	client := blastengine.Initialize(apiKey, userId)
	
	// 以下、ログ取得のコード
}
```

### 基本的なログ取得

パラメータなしで全てのログを取得する最もシンプルな例：

```go
// パラメータなしでGetLogsを呼び出す
params := &blastengine.GetLogsParams{}
logs, err := client.GetLogs(params)

if err != nil {
	fmt.Printf("ログ取得に失敗しました: %v\n", err)
	return
}

// 取得したログを処理
for _, log := range logs {
	fmt.Printf("メールアドレス: %s, ステータス: %s, 配信時間: %v\n", 
		log.Email, log.Status, log.DeliveryTime)
}
```

### 特定のメールアドレスのログを取得

特定のメールアドレス宛のメールのログだけを取得する例：

```go
params := &blastengine.GetLogsParams{
	Email: "test@example.com",
	Count: 10, // 最大10件取得
}
logs, err := client.GetLogs(params)

if err != nil {
	fmt.Printf("ログ取得に失敗しました: %v\n", err)
	return
}

fmt.Printf("%s 宛のメールログを %d 件取得しました\n", params.Email, len(logs))
```

### 配信タイプでフィルタリング

バルクメールとトランザクションメールを区別してログを取得する例：

```go
params := &blastengine.GetLogsParams{
	DeliveryType: []string{"BULK"}, // バルクメールのみ
	Count:        10,
}
logs, err := client.GetLogs(params)

if err != nil {
	fmt.Printf("ログ取得に失敗しました: %v\n", err)
	return
}

fmt.Printf("バルクメールのログを %d 件取得しました\n", len(logs))
```

### 配信期間でフィルタリング

特定の期間内に配信されたメールのログを取得する例：

```go
// 現在時刻から1週間前
oneWeekAgo := time.Now().AddDate(0, 0, -7)

params := &blastengine.GetLogsParams{
	DeliveryStart: oneWeekAgo,
	DeliveryEnd:   time.Now(),
	Count:         20,
}
logs, err := client.GetLogs(params)

if err != nil {
	fmt.Printf("ログ取得に失敗しました: %v\n", err)
	return
}

fmt.Printf("過去1週間のメールログを %d 件取得しました\n", len(logs))
```

### ステータスでフィルタリング

特定のステータスのメールログを取得する例：

```go
params := &blastengine.GetLogsParams{
	Status: []string{"SENT", "SOFTERROR"},
	Count:  10,
}
logs, err := client.GetLogs(params)

if err != nil {
	fmt.Printf("ログ取得に失敗しました: %v\n", err)
	return
}

fmt.Println("送信済みまたはソフトエラーのメールログ:")
for _, log := range logs {
	fmt.Printf("メールアドレス: %s, ステータス: %s\n", log.Email, log.Status)
}
```

### レスポンスコードでフィルタリング

特定のSMTPレスポンスコードのメールログを取得する例：

```go
params := &blastengine.GetLogsParams{
	ResponseCode: []string{"250", "550"},
	Count:        10,
}
logs, err := client.GetLogs(params)

if err != nil {
	fmt.Printf("ログ取得に失敗しました: %v\n", err)
	return
}

fmt.Println("レスポンスコード250または550のメールログ:")
for _, log := range logs {
	fmt.Printf("メールアドレス: %s, レスポンスコード: %s, メッセージ: %s\n", 
		log.Email, log.LastResponseCode, log.LastResponseMessage)
}
```

### 複数のパラメータを組み合わせたフィルタリング

より複雑な条件でログを取得する例：

```go
// 現在時刻から1週間前
oneWeekAgo := time.Now().AddDate(0, 0, -7)

params := &blastengine.GetLogsParams{
	DeliveryType:  []string{"BULK"},
	Status:        []string{"SENT"},
	DeliveryStart: oneWeekAgo,
	DeliveryEnd:   time.Now(),
	Count:         5,
}
logs, err := client.GetLogs(params)

if err != nil {
	fmt.Printf("ログ取得に失敗しました: %v\n", err)
	return
}

fmt.Println("過去1週間に送信成功したバルクメールのログ:")
for _, log := range logs {
	fmt.Printf("メールアドレス: %s, 配信時間: %v\n", log.Email, log.DeliveryTime)
}
```

### ページネーション

大量のログを取得する場合、ページネーションを使用して分割取得することができます：

```go
// 最初の10件を取得
firstParams := &blastengine.GetLogsParams{
	Count: 10,
}
firstLogs, err := client.GetLogs(firstParams)
if err != nil || len(firstLogs) == 0 {
	fmt.Printf("最初のログ取得に失敗しました: %v\n", err)
	return
}

// 最後のログのIDをアンカーとして使用
anchor := firstLogs[len(firstLogs)-1].MaillogId

// 次の5件を取得
nextParams := &blastengine.GetLogsParams{
	Anchor: anchor,
	Count:  5,
}
nextLogs, err := client.GetLogs(nextParams)
if err != nil {
	fmt.Printf("次のログ取得に失敗しました: %v\n", err)
	return
}

fmt.Printf("次の %d 件のログを取得しました\n", len(nextLogs))
```

## ログデータの活用方法

取得したログデータは様々な用途に活用できます：

### 配信成功率の分析

```go
params := &blastengine.GetLogsParams{
	DeliveryId: yourDeliveryId, // 特定の配信ID
}
logs, err := client.GetLogs(params)
if err != nil {
	return
}

total := len(logs)
success := 0
for _, log := range logs {
	if log.Status == "SENT" {
		success++
	}
}

successRate := float64(success) / float64(total) * 100
fmt.Printf("配信成功率: %.2f%%\n", successRate)
```

### エラー分析

```go
params := &blastengine.GetLogsParams{
	DeliveryId: yourDeliveryId,
	Status:     []string{"HARDERROR", "SOFTERROR"},
}
logs, err := client.GetLogs(params)
if err != nil {
	return
}

fmt.Println("エラーが発生したメール:")
for _, log := range logs {
	fmt.Printf("メールアドレス: %s, ステータス: %s, エラー: %s\n", 
		log.Email, log.Status, log.LastResponseMessage)
}
```

### 開封率の分析

```go
params := &blastengine.GetLogsParams{
	DeliveryId: yourDeliveryId,
	Status:     []string{"SENT"},
}
logs, err := client.GetLogs(params)
if err != nil {
	return
}

total := len(logs)
opened := 0
for _, log := range logs {
	if !log.OpenTime.IsZero() {
		opened++
	}
}

openRate := float64(opened) / float64(total) * 100
fmt.Printf("開封率: %.2f%%\n", openRate)
```

## まとめ

blastengineのGo SDKを使用することで、メール配信ログを簡単に取得し、分析することができます。これにより、メール配信の効果を測定し、問題を特定して改善することが可能になります。

ログデータは、マーケティングキャンペーンの効果測定やシステムの健全性確認など、様々な用途に活用できます。blastengineのAPIとSDKを活用して、より効果的なメール配信システムを構築しましょう。

[エンジニア向けメール配信システム「ブラストエンジン」](https://blastengine.jp/)