API リファレンス

メールを送信

公開済みテンプレートとアプリのデータでメールを送信します。

リクエスト

POST /api/v1/emails

項目	必須	説明
`to`	はい	宛先 1 件。最大 255 文字。
`template`	はい	プロジェクト内のテンプレートキー。最大 100 文字。小文字の英字・数字・`_`・`-` を使い、先頭は英字または数字。
`data`	はい	テンプレート変数のオブジェクト。変数がない場合は `{}`。
`locale`	いいえ	`ja` や `en-gb` などの公開済み言語タグ。省略するとテンプレートの既定言語。
`version`	いいえ	公開済みバージョン番号。省略時は最新バージョン。
`attachments`	いいえ	このメールに添付するファイル。

リクエスト例

your-template を公開済みテンプレートのキーに、data をそのテンプレートの変数に置き換えてください。

サンプルの言語

cURL

curl https://sendery.co/api/v1/emails \
  -H "Authorization: Bearer $SENDERY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "to": "[email protected]",
    "template": "your-template",
    "data": {"name": "Alex", "action_url": "https://example.com/start"}
  }'

PHP

require 'vendor/autoload.php';

use Sendery\Client;

$sendery = new Client(getenv('SENDERY_API_KEY'));
$receipt = $sendery->send(
    to: '[email protected]',
    template: 'your-template',
    data: ['name' => 'Alex', 'action_url' => 'https://example.com/start'],
);

echo $receipt['id'];

JavaScript

import { Sendery } from '@sendery/sdk';

const apiKey = process.env.SENDERY_API_KEY;
if (!apiKey) throw new Error('Set SENDERY_API_KEY on your server.');

const sendery = new Sendery(apiKey);
const receipt = await sendery.send({
  to: '[email protected]',
  template: 'your-template',
  data: { name: 'Alex', action_url: 'https://example.com/start' },
});

console.log(receipt.id);

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/sendery-co/sendery-go"
)

func main() {
	client, err := sendery.NewClient(os.Getenv("SENDERY_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}

	receipt, err := client.Send(context.Background(), sendery.SendEmailInput{
		To:       "[email protected]",
		Template: "your-template",
		Data: map[string]any{
			"name":       "Alex",
			"action_url": "https://example.com/start",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(receipt.ID)
}

Python

import os
from sendery import Sendery

sendery = Sendery(os.environ["SENDERY_API_KEY"])
receipt = sendery.send(
    to="[email protected]",
    template="your-template",
    data={"name": "Alex", "action_url": "https://example.com/start"},
)

print(receipt["id"])

Java

import co.sendery.Sendery;
import java.util.Map;

public class SendEmail {
    public static void main(String[] args) {
        var sendery = new Sendery(System.getenv("SENDERY_API_KEY"));
        var receipt = sendery.send("[email protected]", "your-template", Map.of(
            "name", "Alex",
            "action_url", "https://example.com/start"
        ));
        System.out.println(receipt.id());
    }
}

Kotlin

import co.sendery.Sendery

fun main() {
    val sendery = Sendery(System.getenv("SENDERY_API_KEY"))
    val receipt = sendery.send("[email protected]", "your-template", mapOf(
        "name" to "Alex",
        "action_url" to "https://example.com/start"
    ))
    println(receipt.id())
}

レスポンス

新規送信は 202 と id、status を返します。同じ Idempotency-Key と内容で受付済みリクエストを再試行すると、200 と元の ID、現在の状態を返します。下書きの変更や再公開は受付済みメールには反映されません。

202 · application/json

{
  "id": "35a6b227-1748-412e-8651-430492201670",
  "status": "queued",
  "sandbox_url": "https://sendery.co/en/app/projects/5656/activity/35a6b227-1748-412e-8651-430492201670"
}

変数と上限

テンプレートの変数を data に指定します。未指定のテキストは空欄になり、画像などの動的コンテンツは値がなければ表示されません。変数が不足しているリクエストを拒否するには、プロジェクト設定で「APIリクエストを厳密に検証する」を有効にしてください。非表示のブロックだけで使う変数は常に省略できます。

値には文字列・数値・真偽値、または明細ブロック用のオブジェクト配列を使用できます。null とネストしたオブジェクトには対応していません。

対象	上限
JSON リクエスト本文（エンコード後の添付ファイルを含む）	8 MB（8,388,608 バイト）
1通あたりの添付ファイル数	10
base64変換前の合計ファイルサイズ	5 MB（5,242,880 バイト）
JSON `data` の合計	200,000 バイト
`data` の変数数	50
単一値	65,536 バイト
配列の行数	100
1 行の項目数	10
行内の値	2,000 バイト

生成後のメールが大きすぎる場合は 422 を返します。繰り返し使う内容や長い変数を減らしてください。

送信者と内容

送信者はプロジェクト、件名と本文はテンプレートで設定します。リクエストに指定できる項目は to、template、data、locale、version、attachments です。html、subject、from、cc、bcc、複数宛先には対応していません。

特定のバージョンを送信

version にテンプレートの公開履歴にあるバージョン番号を指定します。省略すると最新バージョンを使います。履歴に残っていないバージョンは 422 validation_error を返します。

JSON

{
  "to": "[email protected]",
  "template": "your-template",
  "data": {
    "name": "Alex",
    "action_url": "https://example.com/start"
  },
  "version": 3
}

添付ファイル

1通につき最大 10ファイル、base64変換前で合計 5 MB まで添付できます。送信リクエストに attachments 配列を追加してください。

フィールド	必須	説明
`filename`	はい	受信者に表示するファイル名。ディレクトリのパスは含めません。
`content`	はい	base64に変換したファイルの内容。空白や `data:` 接頭辞は含めません。
`content_type`	いいえ	`application/pdf` などのMIME型。

URLではなくファイルの内容を渡してください。インライン添付や、実行可能ファイルを含む一部の形式には対応していません。添付ファイルはメール履歴からは確認できません。

送信を再試行する場合は、添付ファイルと冪等キーを変更しないでください。

使用例

curl https://sendery.co/api/v1/emails \
  -H "Authorization: Bearer $SENDERY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-idempotency-key' \
  -d '{
    "to": "[email protected]",
    "template": "your-template",
    "data": {"name": "Alex", "action_url": "https://example.com/start"},
    "attachments": [{
      "filename": "document.txt",
      "content": "SGVsbG8sIEFseCE=",
      "content_type": "text/plain"
    }]
  }'