Developer Docs

Connect a sending domain, create an API key, and send transactional email from your backend.

Start here

Quickstart

GoSend is designed for backend-triggered transactional email: signups, password resets, audit notifications, support tickets, and system alerts.

Choose a sending path

Use Sender Accounts when you already have SMTP or Resend credentials. In that mode, GoSend sends from the account's default from email and does not require GoSend domain verification. Use Domains only when GoSend manages sending through AWS SES.

Verify AWS SES domains

If you send through GoSend-managed AWS SES, add the domain in Domains and complete DKIM, SPF, MAIL FROM, and DMARC DNS records before sending. This step is not required for your own sender accounts.

Create an API key

Create one API key for your backend. Store the token in your server environment and never expose it in frontend code.

Create a webhook key

Optional: open Webhooks, add your HTTPS callback endpoint, and copy the generated webhook key. Pass this key as webhook_key only for messages that should trigger callbacks.

Send your first email

Call POST /api/v1/emails from your backend with an allowed sender, recipient list, subject, and HTML body. The API returns a queued message id immediately.

DNS

Domain Verification

Domain verification is required only for GoSend-managed AWS SES sending. If you configure your own SMTP or Resend sender account, GoSend does not require domain verification and does not add that domain to Domains automatically.

Sending path	GoSend domain verification	When to use it
Own SMTP / Resend sender account	Not required	Use this when the sender is controlled by the configured provider account, even if the domain DNS is not controlled by the GoSend user.
GoSend-managed AWS SES	Required before sending	Use this when GoSend should create and verify the sending identity through AWS SES.

Record	Type	Purpose
DKIM	CNAME	Proves that GoSend is allowed to sign mail for your domain.
SPF	TXT	Allows AWS SES mail servers to send on behalf of your domain.
MAIL FROM	MX/TXT	Improves bounce handling and aligns the return-path domain.
DMARC	TXT	Tells receiving mailboxes how to handle unauthenticated messages.

DNS propagation can take a few minutes or longer depending on the provider. GoSend checks public DNS and the SES identity status before allowing GoSend-managed AWS SES send requests. For your own sender account, GoSend only checks that the from address matches the account's default from email; the email provider decides whether that sender is allowed.

API

Authentication

Authenticate Email API requests with a bearer token. API keys belong to one user account and should only be used from trusted backend environments.

Authorization: Bearer gs_xxxxxxxxxxxxxxxxxxxxx

Endpoint

Send Email

Use this endpoint to queue one transactional email. The from address must either match your configured sender account's default from email or use a verified GoSend-managed AWS SES domain.

curl -X POST https://www.gosend.dev/api/v1/emails \
  -H "Authorization: Bearer gs_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "GoSend <noreply@gosend.dev>",
    "to": ["user@gmail.com"],
    "subject": "Welcome",
    "html": "<h1>Hello</h1>",
    "webhook_key": "whsec_optional_webhook_key"
  }'

Request fields

from - Sender name and email address. For own sender accounts, this must match the account's default from email. For AWS SES, the domain must be verified in GoSend.
to - One or more recipient email addresses.
subject - Email subject line.
html - HTML body rendered by recipient mail clients.
webhook_key - Optional webhook key. Events are sent only to the matching webhook when this key is present.

Response

{
  "id": "msg_xxx",
  "status": "queued"
}

Endpoint

Check Email Status

Use the message id returned by the send endpoint to read the latest status for that email. The API key can only access emails that belong to the same account.

curl -X GET https://www.gosend.dev/api/v1/emails/msg_xxx \
  -H "Authorization: Bearer gs_xxxxxxxxxxxxxxxxxxxxx"

Response

{
  "id": "msg_xxx",
  "status": "delivered",
  "from": "GoSend <noreply@gosend.dev>",
  "to": ["user@gmail.com"],
  "subject": "Welcome",
  "provider": "AWS SES",
  "provider_message_id": "010001...",
  "created_at": "2026-06-27T10:00:00.000Z",
  "updated_at": "2026-06-27T10:01:20.000Z"
}

Status values

queued - The message was accepted by GoSend.
sent - The email provider accepted the message.
delivered - The destination mailbox accepted the message.
bounce - The destination mailbox rejected the message.
complaint - The recipient or provider reported the message as unwanted.

Callbacks

Webhooks

Create a webhook endpoint in Dashboard / Webhooks. GoSend generates a webhook key for that endpoint. Email events are sent only when the send request includes this key.

How webhook_key works

Create one webhook for each callback endpoint you want to use.
Copy the generated webhook_key and store it in your backend.
Pass webhook_key in POST /api/v1/emails to bind that message to the matching webhook.
If webhook_key is omitted, GoSend sends the email but does not send lifecycle callbacks to your webhook.
If webhook_key is invalid, the email request is rejected with Invalid webhook key.

Webhook request

POST https://your-app.com/api/gosend/webhook
content-type: application/json
x-gosend-signature: <hmac_sha256>

{
  "event": "email.delivered",
  "email": "user@gmail.com",
  "message_id": "msg_xxx"
}

Multiple webhooks are not broadcast automatically. The webhook_key in each send request selects the single webhook endpoint that should receive events for that email.

Delivery

Email Events

Email logs and webhooks use the same lifecycle language. Webhook events are delivered only when the send request includes a matching webhook_key.

Status	Description
Queued	The request passed validation and is waiting to be sent.
Sent	The provider accepted the message for delivery.
Delivered	A delivery event was received from the provider.
Bounce	The recipient mailbox rejected the message.
Complaint	The recipient or mailbox provider reported the message as unwanted.

{
  "event": "email.delivered",
  "email": "user@gmail.com",
  "message_id": "msg_xxx"
}

Safety

Errors and Limits

GoSend validates sender ownership, API keys, and account quota before a message is queued.

Error	Meaning
401 Unauthorized	Missing, invalid, or revoked API key.
400 Bad Request	Invalid request body, invalid sender email, or invalid webhook_key.
403 Forbidden	The API key is valid, but the sender domain does not belong to this account.
404 Not Found	The requested email id was not found in this account.
422 Unprocessable Entity	The request body is missing required fields or has invalid email addresses.
429 Too Many Requests	The account has exceeded plan quota or rate limits.