Contents
スポンサードリンク
Mailchimp API の認証と基本設定
Mailchimp のマーケティング API を利用する際は 認証方式 と 認証情報の安全な管理 が最も重要です。本セクションでは、公式ドキュメントに基づく正しい認証手順を解説し、環境変数での管理方法まで網羅します。
参考: Mailchimp Authentication Guide（2026‑05 時点）
1. API キー取得と認証方式の選択
1‑1. API キーの発行手順
| 手順 | 操作内容 |
|---|---|
| 1 | Mailchimp にログインし、右上メニューから Account を開く |
| 2 | 左サイドバーの Extras → API keys を選択 |
| 3 | Create A Key ボタンをクリックし、生成された xxxxxxxxxxxxxx-usX（例） をコピー |
1‑2. 推奨される認証方式
Mailchimp が公式にサポートしているのは次の 2 種類です。
| 認証方式 | 送信ヘッダー例 | 主な利用シーン |
|---|---|---|
| Basic 認証（API キー） | Authorization: Basic <base64(username:apikey)> |
シンプルなサーバーサイドスクリプトやバッチ処理 |
| OAuth 2.0（アクセストークン） | Authorization: Bearer <access_token> |
複数ユーザーが利用する SaaS アプリや、トークンの有効期限を管理したい場合 |
ポイント
- API キーそのものは Bearer トークンとして直接使用できません。Mailchimp ではAuthorization: Bearer <key>は認められておらず、Basic 認証か OAuth2 が必須です（公式ドキュメント参照）。
- Basic 認証のusername部分は任意の文字列で構いませんが、一般的に"anystring"もしくはメールアドレスを設定します。
1‑3. Basic 認証ヘッダーの作り方（言語別）
| 言語 | ヘッダー生成コード例 |
|---|---|
| Node.js | js<br>const apiKey = process.env.MAILCHIMP_API_KEY;<br>const auth = Buffer.from( |
| Python | python<br>import os, base64<br>api_key = os.getenv('MAILCHIMP_API_KEY')<br>auth = base64.b64encode(f'anystring:{api_key}'.encode()).decode()<br>headers = {'Authorization': f'Basic {auth}'} |
| cURL | bash<br>API_KEY=xxxxxxxxxxxxxx-usX<br>AUTH=$(echo -n "anystring:${API_KEY}" | base64)<br>curl -H "Authorization: Basic ${AUTH}" https://usX.api.mailchimp.com/3.0/... |
2. 認証情報を環境変数で安全に管理する
2‑1. 環境変数の基本方針
- コードベースに認証情報を書かない
.envファイルは.gitignoreに必ず追加 し、リポジトリ外部へ漏洩しないようにする- 本番環境では CI/CD ツールやクラウドプロバイダーのシークレット管理機能を利用
2‑2. .env の例とロード方法
|
1 2 3 |
# .env（必ず .gitignore に追加してください） MAILCHIMP_API_KEY=xxxxxxxxxxxxxx-usX |
Node.js (dotenv)
|
1 2 3 |
require('dotenv').config(); const apiKey = process.env.MAILCHIMP_API_KEY; // ここで取得したキーを上記の Basic 認証に利用 |
Python (python-dotenv)
|
1 2 3 4 5 6 |
from dotenv import load_dotenv import os load_dotenv() api_key = os.getenv('MAILCHIMP_API_KEY') |
画像を File Manager にアップロードする手順
Mailchimp のマーケティングキャンペーンでは、本文に直接画像ファイルを添付できません。代わりに File Manager API (/file-manager/files) を利用して CDN 上にホストし、その URL を埋め込みます。
1. 必要なパラメータとリクエスト形式
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
type |
string | ○ | 固定値 "image" |
name |
string | ○ | 任意のファイル名（拡張子必須） |
file |
binary | ○ | 画像データ本体 |
folder_id |
string | △ | フォルダに格納したい場合は指定 |
リクエストは multipart/form-data で送信し、ヘッダーには前節で作成した Basic 認証を付与します。
2. 実装サンプル
cURL
|
1 2 3 4 5 6 7 8 9 10 |
#!/usr/bin/env bash API_KEY=xxxxxxxxxxxxxx-usX AUTH=$(echo -n "anystring:${API_KEY}" | base64) curl -X POST "https://usX.api.mailchimp.com/3.0/file-manager/files" \ -H "Authorization: Basic ${AUTH}" \ -F "type=image" \ -F "name=sample.jpg" \ -F "file=@./sample.jpg" |
Node.js (axios + form-data)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
const axios = require('axios'); const FormData = require('form-data'); const fs = require('fs'); require('dotenv').config(); async function uploadImage() { const apiKey = process.env.MAILCHIMP_API_KEY; const auth = Buffer.from(`anystring:${apiKey}`).toString('base64'); const form = new FormData(); form.append('type', 'image'); form.append('name', 'sample.jpg'); form.append('file', fs.createReadStream('./sample.jpg')); const response = await axios.post( 'https://usX.api.mailchimp.com/3.0/file-manager/files', form, { headers: { ...form.getHeaders(), Authorization: `Basic ${auth}`, }, } ); console.log(response.data); } uploadImage().catch(console.error); |
Python (requests)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
import os, base64, requests from dotenv import load_dotenv load_dotenv() api_key = os.getenv('MAILCHIMP_API_KEY') auth = base64.b64encode(f'anystring:{api_key}'.encode()).decode() url = 'https://usX.api.mailchimp.com/3.0/file-manager/files' files = { 'type': (None, 'image'), 'name': (None, 'sample.jpg'), 'file': ('sample.jpg', open('sample.jpg', 'rb'), 'image/jpeg') } headers = {'Authorization': f'Basic {auth}'} resp = requests.post(url, files=files, headers=headers) print(resp.json()) |
アップロードした画像情報の取得とメール本文への埋め込み
1. レスポンスから必要なデータを抽出
アップロードが成功すると次のような JSON が返ります。
|
1 2 3 4 5 6 7 8 |
{ "id": "12345678abcd", "type": "image", "name": "sample.jpg", "full_size_url": "https://cdn-images.mailchimp.com/12345678abcd/sample.jpg", "created_at": "2026-05-09T12:34:56+00:00" } |
| フィールド | 用途 |
|---|---|
id |
後続の API（削除やメタ情報更新）で使用 |
full_size_url |
キャンペーン本文に埋め込む画像 URL |
Python 例
|
1 2 3 4 5 |
data = resp.json() file_id = data['id'] image_url = data['full_size_url'] print(f'File ID: {file_id}\nImage URL: {image_url}') |
2. HTML の <img> タグに組み込むベストプラクティス
- インライン CSSで幅と高さを明示し、レスポンシブ対応
alt属性は必ず設定（アクセシビリティとクライアントの画像非表示対策）
|
1 2 3 4 5 |
<img src="https://cdn-images.mailchimp.com/12345678abcd/sample.jpg" width="600" style="max-width:100%; height:auto; display:block;" alt="キャンペーン用サンプル画像"> |
Campaign Content API で画像入りメール本文を作成
1. エンドポイントとリクエスト概要
| 項目 | 内容 |
|---|---|
| メソッド | PUT |
| URL | https://usX.api.mailchimp.com/3.0/campaigns/{campaign_id}/content |
| 認証ヘッダー | Basic 認証（前述） |
| Content-Type | application/json |
| 必須ボディフィールド | html （画像タグを含む HTML 文字列） |
2. 実装例
cURL
|
1 2 3 4 5 6 7 8 9 10 11 12 |
#!/usr/bin/env bash CAMPAIGN_ID=YOUR_CAMPAIGN_ID API_KEY=xxxxxxxxxxxxxx-usX AUTH=$(echo -n "anystring:${API_KEY}" | base64) curl -X PUT "https://usX.api.mailchimp.com/3.0/campaigns/${CAMPAIGN_ID}/content" \ -H "Authorization: Basic ${AUTH}" \ -H "Content-Type: application/json" \ -d '{ "html": "<p>新商品をご紹介します。</p><img src=\"https://cdn-images.mailchimp.com/12345678abcd/sample.jpg\" width=\"600\" style=\"max-width:100%;height:auto;display:block;\" alt=\"新商品画像\">" }' |
Node.js (axios)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
const axios = require('axios'); require('dotenv').config(); async function updateCampaign(campaignId, imageUrl) { const apiKey = process.env.MAILCHIMP_API_KEY; const auth = Buffer.from(`anystring:${apiKey}`).toString('base64'); const html = ` <p>新商品をご紹介します。</p> <img src="${imageUrl}" width="600" style="max-width:100%;height:auto;display:block;" alt="新商品画像"> `; const response = await axios.put( `https://usX.api.mailchimp.com/3.0/campaigns/${campaignId}/content`, { html }, { headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json', }, } ); console.log('Campaign updated:', response.data); } updateCampaign('YOUR_CAMPAIGN_ID', 'https://cdn-images.mailchimp.com/12345678abcd/sample.jpg') .catch(console.error); |
Python (requests)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
import os, json, base64, requests from dotenv import load_dotenv load_dotenv() api_key = os.getenv('MAILCHIMP_API_KEY') auth = base64.b64encode(f'anystring:{api_key}'.encode()).decode() campaign_id = 'YOUR_CAMPAIGN_ID' image_url = 'https://cdn-images.mailchimp.com/12345678abcd/sample.jpg' html = f''' <p>新商品をご紹介します。</p> <img src="{image_url}" width="600" style="max-width:100%;height:auto;display:block;" alt="新商品画像"> ''' url = f'https://usX.api.mailchimp.com/3.0/campaigns/{campaign_id}/content' headers = { 'Authorization': f'Basic {auth}', 'Content-Type': 'application/json', } payload = json.dumps({'html': html}) resp = requests.put(url, headers=headers, data=payload) print(resp.json()) |
エラーハンドリングとデバッグのポイント
1. 主なステータスコードと対処法
| ステータス | 主な原因 | 推奨される対策 |
|---|---|---|
| 400 Bad Request | パラメータ不足、JSON の構文エラー | リクエストボディを JSON 形式で正しく整形 |
| 401 Unauthorized | API キーが無効、ヘッダーの書式ミス | Authorization: Basic <base64> が正しいか再確認 |
| 403 Forbidden | アカウント権限不足（例：File Manager の利用不可） | プランとユーザー権限を Mailchimp コンソールで確認 |
| 404 Not Found | 指定した campaign_id や file_id が存在しない |
GET /campaigns で ID を取得し直す |
| 429 Too Many Requests | レートリミット超過 | Exponential back‑off（例：2^n 秒）で再試行 |
| 500 系 | Mailchimp 側の一時的障害 | 後ほど再実行、ステータスページを確認 |
2. 実装上のデバッグ手順
- レスポンスボディを必ず出力し、
detailフィールドに含まれるエラーメッセージを読む。 - リクエストヘッダー（特に
Authorization）が期待通りかcurl -vや axios のインターセプタで確認する。 - 公式リファレンスでパラメータ仕様を再チェック：https://mailchimp.com/developer/marketing/api/
3. 汎用的なリトライロジック（Node.js）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
const axios = require('axios'); async function requestWithRetry(config, maxAttempts = 4) { for (let attempt = 1; attempt <= maxAttempts; attempt++) { try { const res = await axios(config); return res.data; } catch (err) { const status = err.response?.status; console.warn(`Attempt ${attempt} failed – HTTP ${status}`); // 429 は待機してリトライ、他の 5xx 系も同様に if ((status === 429 || (status >= 500 && status < 600)) && attempt < maxAttempts) { const wait = Math.pow(2, attempt) * 1000; // 2,4,8 秒… await new Promise(r => setTimeout(r, wait)); continue; } // 4xx 系は設定ミスが多いので即時例外 throw err; } } } |
補足情報・代替手段・ベストプラクティス
1. 画像サイズと CDN の特性
- サポート形式：JPEG, PNG, GIF（※WebP は非対応）
- 推奨最大サイズ 2 MB 未満、幅は 600 px 前後 にリサイズすると多くのメールクライアントで最適表示
- アップロード直後に生成される CDN URL はデフォルトで 24 時間 キャッシュ。即時更新したい場合は
?v=YYYYMMDDHHMMのようなクエリ文字列を付与するとキャッシュバイパスが可能
2. 添付ファイルが必要なケース（Mandrill / Mailchimp Transactional）
マーケティングキャンペーンでは画像は CDN 埋め込みのみですが、トランザクションメールで PDF や画像を添付したい場合は Mailchimp Transactional (旧 Mandrill) が利用できます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
import mandrill, base64, os from dotenv import load_dotenv load_dotenv() client = mandrill.Mandrill(os.getenv('MANDRILL_API_KEY')) with open('invoice.pdf', 'rb') as f: pdf_b64 = base64.b64encode(f.read()).decode() message = { "html": "<p>ご請求書をご確認ください。</p>", "subject": "ご請求書", "from_email": "sales@example.com", "to": [{"email": "customer@example.com"}], "attachments": [{ "type": "application/pdf", "name": "invoice.pdf", "content": pdf_b64 }] } print(client.messages.send(message=message)) |
3. CI/CD 環境でのシークレット管理例
| プラットフォーム | 推奨設定 |
|---|---|
| GitHub Actions | secrets.MAILCHIMP_API_KEY を環境変数にエクスポート |
| GitLab CI | variables: で MAILCHIMP_API_KEY を定義し、protected にしてブランチ制限 |
| AWS CodeBuild | Parameter Store / Secrets Manager の ARN をビルドロールに付与 |
4. ログとモニタリングのベストプラクティス
- リクエスト ID（レスポンスヘッダー
x-request-id）を取得し、障害時に検索できるようログに残す。 - エラーレートが 5 % 以上 継続したら Slack/Teams に自動通知する仕組みを構築。
- 本番環境でのテストは必ず ステージングアカウント（別データセンター）で実施し、実際にメールが送信されるか検証する。
参考リンク
| 内容 | URL |
|---|---|
| Mailchimp API ルートドキュメント | https://mailchimp.com/developer/marketing/api/ |
| 認証ガイド（Basic & OAuth2） | https://mailchimp.com/developer/marketing/guides/authentication/ |
| File Manager エンドポイント仕様 | https://mailchimp.com/developer/marketing/api/file-manager/files/ |
| Campaign Content API 仕様 | https://mailchimp.com/developer/marketing/api/campaigns/content/ |
| Mailchimp Transactional (Mandrill) ドキュメント | https://mailchimp.com/developer/transactional/api/ |
まとめ
- Mailchimp の認証は Basic 認証（API キー）か OAuth2 が正式サポート。Authorization: Bearer <key>は利用不可です。
- 環境変数に API キーを保存し、Base64 エンコードした文字列でAuthorization: Basic …を送ります。
- 画像は File Manager API に multipart/form-data でアップロードし、取得した CDN URL を<img>タグに埋め込んで Campaign Content API で本文を更新します。
- エラーハンドリング・リトライロジックとモニタリングを組み合わせれば、安定した自動配信基盤が構築できます。
これらの手順とベストプラクティスに沿って実装すれば、Mailchimp API を安全かつ効果的に活用できるでしょう。
スポンサードリンク