Cara Mendapatkan Kunci API Resend dan Mengirim Email Pertama Anda

Resend adalah API email yang dibuat untuk pengembang: satu permintaan POST, satu badan JSON, dan email transaksional akan terkirim. Setiap permintaan membutuhkan kunci API, dan bagaimana Anda membuat kunci tersebut menentukan seberapa besar kerusakan yang bisa ditimbulkan jika kunci tersebut bocor. Panduan ini menjelaskan seluruh langkah: mendaftar, memverifikasi domain pengirim (atau menggunakan alamat pengujian bawaan), membuat kunci dengan cakupan izin yang benar, dan mengirim email pertama Anda dengan curl, Node, dan Python. Anda juga akan menyimpan kunci tersebut di Apidog sehingga Anda dapat menguji endpoint tanpa menempelkan rahasia ke shell Anda.

Jika Anda ingin gambaran lebih luas tentang fungsi API di luar pengiriman, panduan pemula API Resend mencakup sisanya. Semua yang tercantum di bawah ini telah diperiksa berdasarkan dokumen resmi Resend, sehingga angka dan string kesalahan akan sesuai dengan yang Anda lihat.

button

Apa yang Anda butuhkan sebelum memulai

Akun Resend. Paket gratis sudah cukup untuk tutorial ini.
Domain yang Anda kontrol. Jika Anda tidak memilikinya, alamat uji coba sudah cukup untuk pengiriman pertama.
curl di mesin Anda, ditambah Node.js atau Python jika Anda ingin contoh SDK.
Apidog terinstal jika Anda berencana mengikuti bagian pengujian.

Langkah 1: membuat akun Resend

Daftar di resend.com dan konfirmasi email Anda. Catat alamat yang Anda gunakan untuk mendaftar: sampai Anda memverifikasi domain, itu adalah satu-satunya kotak masuk tempat Resend akan mengirimkan email pengujian, dan melupakannya menyebabkan kesalahan 403 paling membingungkan yang akan Anda lihat di hari pertama.

Langkah 2: verifikasi domain pengirim, atau gunakan alamat pengujian

Dua jalur; mulai dengan yang cepat.

Jalur A: alamat pengujian orientasi. Resend memungkinkan Anda mengirim dari onboarding@resend.dev tanpa pengaturan. Tangkapannya adalah penerima: itu harus email akun Anda sendiri. Kirim ke orang lain dan API akan mengembalikan 403 dengan pesan “Anda hanya dapat mengirim email pengujian ke alamat email Anda sendiri”.

Jalur B: domain Anda sendiri. Untuk apa pun yang nyata, tambahkan domain di dasbor di bawah Domains. Resend merekomendasikan subdomain seperti notifications.example.com daripada domain utama Anda, agar reputasi pengiriman produk Anda tetap terpisah dari surat perusahaan Anda. Pilih wilayah terdekat dengan penerima Anda, lalu salin catatan DNS yang dibuat Resend ke penyedia DNS Anda. Dokumen menjelaskan catatan tersebut sebagai “konfigurasi DKIM dan SPF (catatan TXT dan MX atau CNAME)”. Subdomain Return-Path secara default adalah send.example.com.

Verifikasi biasanya selesai dalam 15 menit, meskipun propagasi DNS bisa memakan waktu hingga 72 jam. Jika macet, periksa dua penyebab klasik: catatan ditempatkan di root alih-alih subdomain send, dan proxy Cloudflare (ikon awan harus abu-abu, bukan oranye). Perbaiki catatan, lalu klik “Restart verification”. Tambahkan catatan DMARC setelahnya; ini tidak wajib untuk mengirim, tetapi penyedia kotak masuk menghargainya.

Langkah 3: buat kunci API dengan cakupan yang tepat

Buka halaman kunci API di dasbor dan klik Buat Kunci API. Tiga bidang penting; dokumen buat kunci API mencakup masing-masing:

Nama. Maksimal 50 karakter. Beri nama sesuai aplikasi dan lingkungan, seperti billing-service-prod, agar kunci mudah dibedakan nanti.
Izin. “Akses penuh” dapat membuat, menghapus, mendapatkan, dan memperbarui sumber daya apa pun, termasuk domain dan kunci API lainnya. “Akses pengiriman” hanya dapat mengirim email. Pilih akses pengiriman untuk apa pun yang disebarkan. Kunci akses penuh hanya boleh ada di laptop Anda, atau tidak sama sekali.
Domain. Dengan akses pengiriman, Anda dapat membatasi kunci ke satu domain yang diverifikasi. Kunci yang cakupannya ke notifications.example.com tidak dapat mengirim dari billing.example.com, yang membatasi dampak kebocoran.

Resend menampilkan kunci persis satu kali. Kunci tersebut dimulai dengan re_, dan setelah Anda menutup dialog, Anda dapat mengganti nama kunci tetapi tidak dapat melihatnya lagi. Salin langsung ke variabel lingkungan:

export RESEND_API_KEY="re_xxxxxxxxx"

Panduan Resend sendiri: kunci tidak pernah kedaluwarsa, jadi rotasikan setiap 90 hari atau lebih cepat; dasbor menandai kunci apa pun yang tidak digunakan selama 30 hari; dan jika kunci bocor, segera hapus alih-alih menunggu rotasi berikutnya. Mengirim string re_ ke git adalah jalur kebocoran paling umum, jadi jalankan pemindai rahasia pada repositori Anda sebelum dorongan pertama.

Anda juga dapat membuat kunci dengan POST https://api.resend.com/api-keys, dengan meneruskan name, permission (full_access atau sending_access), dan domain_id opsional. Panggilan itu membutuhkan kunci akses penuh, satu alasan lagi untuk hanya menyimpan satu kunci semacam itu.

Langkah 4: kirim email pertama Anda

Endpoint pengiriman adalah POST https://api.resend.com/emails. Autentikasi adalah token Bearer di header Authorization, badan adalah JSON, dan hanya HTTPS yang diterima. Tiga bidang wajib: from, to, dan subject. Tambahkan html, text, atau keduanya; jika Anda hanya mengirim html, Resend akan menghasilkan bagian teks biasa. to menerima string atau array hingga 50 alamat. Daftar parameter lengkap ada di referensi pengiriman email.

curl

curl -X POST 'https://api.resend.com/emails' \
  -H "Authorization: Bearer $RESEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <onboarding@resend.dev>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>"
  }'

Panggilan yang berhasil mengembalikan {"id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"}. Satu keunikan: setiap permintaan harus membawa header User-Agent, atau API akan menjawab 403 dengan kode 1010. Curl dan SDK mengaturnya; klien yang dibuat secara manual dalam runtime edge mungkin tidak.

Node.js

npm install resend

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

const { data, error } = await resend.emails.send({
  from: 'Acme <notifications@example.com>',
  to: ['you@yourcompany.com'],
  subject: 'First Resend email',
  html: '<p>Your Resend key works.</p>',
});

if (error) {
  console.error(error);
} else {
  console.log(data.id);
}

Node SDK tidak pernah menimbulkan kesalahan API. Ia mengembalikan { data, error }, jadi periksa error sebelum menyentuh data.id.

Python

pip install resend

import os
import resend
from resend.exceptions import ResendError

resend.api_key = os.environ["RESEND_API_KEY"]

params: resend.Emails.SendParams = {
    "from": "Acme <notifications@example.com>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>",
}

try:
    email = resend.Emails.send(params)
    print(email["id"])
except ResendError as err:
    print(err)

Python SDK melakukan yang sebaliknya: ia menimbulkan ResendError saat gagal, jadi bungkus pengiriman dalam try/except.

Langkah 5: simpan dan uji kunci di Apidog

Curl membuktikan kunci berfungsi sekali. Apidog mengubah pengujian satu kali tersebut menjadi sesuatu yang dapat dijalankan ulang oleh tim Anda, dan menjaga kunci tetap aman dari riwayat shell dan log obrolan.

Simpan kunci sebagai variabel rahasia. Buat lingkungan bernama Resend, tambahkan RESEND_API_KEY sebagai variabel, dan tandai sebagai rahasia agar nilainya disembunyikan di UI dan tidak disertakan dalam ekspor. Panduan lingkungan dan variabel rahasia mencakup pemisahan dev, staging, dan prod jika Anda menyimpan kunci khusus pengiriman yang berbeda per lingkungan, yang seharusnya Anda lakukan.

Kirim permintaan. Buat permintaan POST ke https://api.resend.com/emails, atur Auth ke Bearer Token dengan {{RESEND_API_KEY}}, dan tempel badan JSON dari contoh curl. Tekan Kirim. id akan muncul di panel respons di samping header batas tarif yang dibahas di bawah ini.

Simpan sebagai pengujian. Tambahkan dua pernyataan: status sama dengan 200 dan $.id ada. Tempatkan permintaan ke skenario pengujian dan Anda memiliki uji coba asap yang berjalan setiap kali seseorang menyentuh kode email. Arahkan ke staging dengan kunci pengiriman yang dibatasi domain dan aman untuk dijalankan dari CI.

Mock endpoint untuk pekerjaan frontend. Frontend Anda membutuhkan bentuk respons, bukan pengiriman nyata. Mock endpoint di Apidog sehingga mengembalikan {"id": "mock-email-id"} pada setiap panggilan. Tim UI dapat membangun status “email terkirim” sepanjang hari tanpa menyentuh kuota gratis 100 per hari atau mengirim spam ke kotak masuk yang sebenarnya. Unduh Apidog untuk menyiapkan ini; paket gratis mencakup empat pengguna.

Batasan tingkat gratis yang akan Anda temui pertama

Halaman harga Resend mencantumkan paket gratis sebanyak 3.000 email per bulan, dibatasi 100 per hari, dengan 3 domain dan retensi data 30 hari. Paket Pro dimulai dari $20 per bulan untuk 50.000 email, 10 domain, dan tanpa batas harian, dengan biaya tambahan $0.90 per 1.000 email.

Email uji coba ke alamat resend.dev diperhitungkan dalam kuota tersebut, jadi uji beban yang ditujukan ke delivered@resend.dev tetap menghabiskan 100 harian Anda. bounced@resend.dev, complained@resend.dev, dan suppressed@resend.dev mensimulasikan hard bounce, keluhan spam, dan penerima yang disupresi tanpa alamat buruk yang sebenarnya.

Terpisah dari kuota, batas tarif default adalah 10 permintaan per detik per tim, dibagi di antara setiap kunci di tim. Setiap respons membawa header ratelimit-limit, ratelimit-remaining, ratelimit-reset, dan retry-after, sehingga loop pengiriman dapat mundur sebelum mencapai 429. Butuh lebih banyak? Resend meminta Anda untuk menghubungi dukungan daripada membuat tim tambahan.

Kesalahan umum dan cara memperbaikinya

Setiap kegagalan kembali sebagai JSON dengan statusCode, name, dan message. Ini adalah yang akan Anda temui di hari pertama, dari referensi kesalahan:

Status	Nama	Apa yang terjadi	Perbaikan
401	`missing_api_key`	Tidak ada header `Authorization`	Tambahkan `Authorization: Bearer re_...`
401	`restricted_api_key`	Kunci khusus pengiriman digunakan pada endpoint non-pengiriman	Gunakan kunci akses penuh untuk panggilan tersebut
403	`validation_error`	“Domain tidak diverifikasi”	Selesaikan verifikasi DNS, atau perbaiki alamat `from`
403	`validation_error`	Alamat pengujian dikirim ke orang lain selain Anda	Kirim ke email akun Anda, atau verifikasi domain
403	`restricted_api_key`	“Kunci API tidak aktif”	Kunci telah dihapus; buat yang baru
422	`missing_required_field`	`from`, `to`, atau `subject` hilang	Periksa isi terhadap referensi
429	`rate_limit_exceeded`	Lebih dari 10 permintaan per detik	Antrekan pengiriman, patuhi `retry-after`
429	`daily_quota_exceeded`	Melebihi 100 email hari ini di paket gratis	Tunggu reset atau upgrade

Kesalahan 401 dengan kunci yang Anda yakini benar biasanya berarti ada baris baru di akhir variabel atau file .env yang tidak pernah dimuat. Keduanya terlihat seperti kunci yang hilang dari sisi API.

FAQ

Bisakah saya melihat kunci API Resend saya lagi setelah membuatnya?

Tidak. Resend menampilkan nilainya hanya sekali saat pembuatan. Jika Anda kehilangannya, buat kunci baru dengan nama dan izin yang sama, terapkan, lalu hapus kunci lama.

Haruskah saya memilih akses penuh atau akses pengiriman?

Akses pengiriman, terbatas pada satu domain, untuk setiap kunci yang keluar dari mesin Anda. Simpan satu kunci akses penuh untuk pekerjaan bergaya dasbor seperti menambahkan domain atau membuat kunci lain, dan jangan pernah mengirimkannya dalam aplikasi.

Bisakah saya menguji pengiriman tanpa memverifikasi domain?

Ya. Gunakan onboarding@resend.dev sebagai alamat from dan email akun Anda sendiri sebagai penerima. Penerima lain akan mengembalikan 403 sampai domain diverifikasi.

Apakah ada cara untuk mengelola Resend dari terminal daripada dasbor?

Ya. Panduan Resend CLI mencakup penginstalan dan menjalankan perintah domain dan email umum tanpa membuka browser.

Apa yang terjadi ketika saya melebihi 100 email dalam sehari di paket gratis?

API mengembalikan 429 dengan daily_quota_exceeded, dan pengiriman dilanjutkan setelah reset harian. Jika Anda secara teratur membutuhkan lebih banyak, paket Pro menghilangkan batasnya, dan rangkuman API email gratis menunjukkan bagaimana tingkat gratis penyedia lain membandingkan.

Kesimpulan

Mendapatkan kunci API Resend membutuhkan waktu dua menit; melakukannya dengan benar membutuhkan waktu lima menit. Verifikasi subdomain, buat kunci khusus pengiriman yang terkunci pada domain tersebut, simpan dalam variabel lingkungan, dan kirim satu email dengan curl untuk mengonfirmasi perjalanan pulang-pergi. Kemudian pindahkan permintaan ke Apidog, simpan pernyataan, dan buat mock endpoint agar sisa tim Anda dapat membangunnya tanpa menghabiskan kuota Anda. Kirimkan kunci dengan kekuatan paling rendah yang masih menyelesaikan pekerjaan.

button