API Reference

Simple email API. Resend-compatible. One line to switch.

Base URL

https://api.emailmate.dev

Coming from Resend?

We export a Resend class. Just change from 'resend' tofrom 'emailmate'. No other changes needed.

Authentication

Authenticate your API requests by including your API key in the Authorization header. You can create API keys in the dashboard.

curl https://api.emailmate.dev/emails \
  -H "Authorization: Bearer em_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Keep your API key secret. Never expose it in client-side code or commit it to version control.

Emails

Send transactional emails programmatically.

POST/v1/emails

Send an email

Request Body

Parameter	Type	Description
`from`required	string	Sender email address. Format: "Name <email@domain.com>"
`to`required	string \| string[]	Recipient email address(es)
`subject`required	string	Email subject line
`html`	string	HTML content of the email
`text`	string	Plain text version of the email
`reply_to`	string \| string[]	Reply-to email address(es)
`cc`	string \| string[]	CC recipients
`bcc`	string \| string[]	BCC recipients
`attachments`	Attachment[]	File attachments
`headers`	object	Custom email headers
`tags`	Tag[]	Email tags for tracking

Example Request

curl -X POST https://api.emailmate.dev/emails \
  -H "Authorization: Bearer em_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <onboarding@acme.com>",
    "to": "user@example.com",
    "subject": "Welcome to Acme",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
  }'

Response

{
  "id": "em_xxxxxxxxxxxxxxxx",
  "object": "email"
}

GET/v1/emails/:id

Retrieve an email by ID

Path Parameters

Parameter	Type	Description
`id`required	string	The email ID

Response

{
  "id": "em_xxxxxxxxxxxxxxxx",
  "object": "email",
  "to": ["user@example.com"],
  "from": "onboarding@acme.com",
  "subject": "Welcome to Acme",
  "html": "<h1>Welcome!</h1>",
  "created_at": "2024-01-01T00:00:00.000Z",
  "last_event": "delivered"
}

Domains

Manage sending domains for your emails.

POST/v1/domains

Add a new domain

Parameter	Type	Description
`name`required	string	Domain name (e.g., acme.com)
`region`	string	AWS SES region. Options: "us-east-1", "eu-west-1"

GET/v1/domains

List all domains

Response

{
  "data": [
    {
      "id": "dom_xxxxxxxx",
      "name": "acme.com",
      "status": "verified",
      "created_at": "2024-01-01T00:00:00.000Z",
      "records": [...]
    }
  ]
}

GET/v1/domains/:id

Get domain details including DNS records

Parameter	Type	Description
`id`required	string	Domain ID

POST/v1/domains/:id/verify

Verify domain DNS records

Parameter	Type	Description
`id`required	string	Domain ID

DELETE/v1/domains/:id

Delete a domain

Parameter	Type	Description
`id`required	string	Domain ID

API Keys

Create and manage API keys for authentication.

POST/v1/api-keys

Create a new API key

Parameter	Type	Description
`name`required	string	A name to identify the key
`permission`	string	"full_access" or "sending_access"

GET/v1/api-keys

List all API keys

Response

{
  "data": [
    {
      "id": "key_xxxxxxxx",
      "name": "Production",
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

DELETE/v1/api-keys/:id

Delete an API key

Parameter	Type	Description
`id`required	string	API key ID

Audiences

Manage contact lists for marketing emails.

POST/v1/audiences

Create an audience

Parameter	Type	Description
`name`required	string	Audience name

GET/v1/audiences

List all audiences

Response

{
  "data": [
    {
      "id": "aud_xxxxxxxx",
      "name": "Newsletter",
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

GET/v1/audiences/:id

Get audience details

Parameter	Type	Description
`id`required	string	Audience ID

DELETE/v1/audiences/:id

Delete an audience

Parameter	Type	Description
`id`required	string	Audience ID

Contacts

Manage contacts within audiences.

POST/v1/audiences/:audience_id/contacts

Add a contact to an audience

Parameter	Type	Description
`email`required	string	Contact email address
`first_name`	string	First name
`last_name`	string	Last name
`unsubscribed`	boolean	Unsubscribe status

GET/v1/audiences/:audience_id/contacts

List contacts in an audience

Parameter	Type	Description
`audience_id`required	string	Audience ID

GET/v1/audiences/:audience_id/contacts/:id

Get a contact

Parameter	Type	Description
`audience_id`required	string	Audience ID
`id`required	string	Contact ID

PATCH/v1/audiences/:audience_id/contacts/:id

Update a contact

Parameter	Type	Description
`first_name`	string	First name
`last_name`	string	Last name
`unsubscribed`	boolean	Unsubscribe status

DELETE/v1/audiences/:audience_id/contacts/:id

Remove a contact

Parameter	Type	Description
`audience_id`required	string	Audience ID
`id`required	string	Contact ID

Templates

Create and manage email templates.

POST/v1/templates

Create a template

Parameter	Type	Description
`name`required	string	Template name
`subject`required	string	Email subject
`html`required	string	HTML content

GET/v1/templates

List all templates

Response

{
  "data": [
    {
      "id": "tpl_xxxxxxxx",
      "name": "Welcome Email",
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

GET/v1/templates/:id

Get template details

Parameter	Type	Description
`id`required	string	Template ID

PATCH/v1/templates/:id

Update a template

Parameter	Type	Description
`name`	string	Template name
`subject`	string	Email subject
`html`	string	HTML content

DELETE/v1/templates/:id

Delete a template

Parameter	Type	Description
`id`required	string	Template ID

Webhooks

Receive real-time notifications for email events.

Event Types

email.sent

email.delivered

email.opened

email.clicked

email.bounced

email.complained

Webhook Payload

{
  "type": "email.delivered",
  "created_at": "2024-01-01T00:00:00.000Z",
  "data": {
    "email_id": "em_xxxxxxxx",
    "from": "onboarding@acme.com",
    "to": ["user@example.com"],
    "subject": "Welcome to Acme"
  }
}

Rate Limits

API rate limits and resource limits depend on your plan.

Plan	Emails	Domains	API Keys	Log Retention	Overage
Free	100/day	1	1	7 days	—
Pro $9/mo	10k/mo	20	5	30 days	$0.40/1k
Scale $19/mo	50k/mo	50	15	90 days	$0.30/1k
BYOS Free	Your SES quota	3	2	7 days	$0.10/1k (AWS)
BYOS Pro $5/mo	Your SES quota	25	10	30 days	$0.10/1k (AWS)

Rate limit headers are included in every response:

X-RateLimit-Limit: 10

X-RateLimit-Remaining: 9

X-RateLimit-Reset: 1704067200

Errors

Standard HTTP status codes with detailed error messages.

Code	Description
200	Success
400	Bad request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not found - Resource doesn't exist
429	Rate limit exceeded
500	Internal server error

Error Response

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid.",
    "docs": "https://emailmate.dev/docs#authentication"
  }
}

Bring Your Own SES

Your AWS account. Your SES quota. Pay AWS directly at $0.10/1,000. We just give you the nice API and dashboard. Free forever.

What you get

90% cheaper - $0.10/1k vs Resend's $0.90/1k
Your reputation - Build your own sending reputation, don't share it
Your limits - Send as fast as your SES quota allows
Unlimited everything - Domains, API keys, no artificial caps

Setup

1Create an IAM user in AWS with SES send permissions
2Go to Settings → Providers in your Emailmate dashboard
3Add your AWS Access Key ID, Secret Access Key, and region
4Verify your domain in SES and start sending

Required IAM Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ses:SendEmail",
        "ses:SendRawEmail"
      ],
      "Resource": "*"
    }
  ]
}

SDKs

New project? Use EmailMate. Coming from Resend? One line change.

Recommended

Emailmate SDK

npm install emailmate
# or
bun add emailmate

import { EmailMate } from 'emailmate';

const emailmate = new EmailMate('em_xxxxxxxxxxxx');

await emailmate.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'user@example.com',
  subject: 'Welcome to Acme',
  html: '<h1>Welcome!</h1>'
});

// With React Email
import { WelcomeEmail } from './emails/welcome';

await emailmate.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'user@example.com',
  subject: 'Welcome',
  react: <WelcomeEmail name="John" />
});

1 line change

Migrating from Resend?

Our SDK exports a Resend class. Just change your import.

// Before
import { Resend } from 'resend';

// After - just change the import
import { Resend } from 'emailmate';

// Everything else stays exactly the same
const resend = new Resend('em_xxxxxxxxxxxx');

await resend.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>World</p>'
});

Other Languages

Python

pip install emailmate

go get github.com/emailmate/emailmate-go

Ruby

gem install emailmate

PHP

composer require emailmate/emailmate-php