Send Email

Start sending emails through the Postflare API.

POST/emails

Requires an API key with the emails:send permission.

Body Parameters

Each email must provide at least one of html, text, or template.

fromstring

Sender email address. Required unless a template supplies a default from.

To include a friendly name, use the format "Your Name <sender@domain.com>".

The address must be on one of your organization's verified domains — the exact domain, not a subdomain of it. Any other address is refused with 403 validation_error ("The example.com domain is not verified. Please, add and verify your domain."); a domain that stops being verified after the request is accepted makes that email fail rather than be sent from another address.

tostring | string[]required

Recipient email address. For multiple addresses, send as an array of strings.

The combined number of addresses across to, cc and bcc may not exceed 50.

subjectstring

Email subject. Required unless a template is used; when omitted, the template's default subject is used.

templateobject

Send with a saved template. The template must be published. Fields you pass explicitly (from, subject, html, text, reply_to) take precedence over the template's defaults.

idstringrequired

The template ID (UUID) or alias. A template that does not exist returns 404 not_found.

variablesobject

Variable values keyed by variable name. Values may be strings or numbers; a template's fallback value is used when a key is omitted.

topic_idstring

Topic ID (UUID) for subscription management. Each recipient is judged on its own: a contact who opted out of the topic is skipped, and an address that is not a contact is sent only when the topic's default subscription is opt-in. A topic that does not exist in your organization returns 404 not_found ("The specified topic was not found.").

bccstring | string[]

Bcc recipient email address. For multiple addresses, send as an array of strings.

ccstring | string[]

Cc recipient email address. For multiple addresses, send as an array of strings.

reply_tostring | string[]

Reply-to email address. At most one address — the message carries a single Reply-To. Pass a string or a one-element array; two or more addresses are refused.

htmlstring

The HTML version of the message.

textstring

The plain text version of the message.

If not provided, the HTML will be used to generate a plain text version.

scheduled_atstring

Schedule email to be sent later. The date should be in natural language (e.g.: in 1 min) or ISO 8601 format (e.g: 2024-08-05T11:52:01.858Z).

Must be within 30 days from now.

headersobject

Custom headers to add to the email.

attachmentsarray

Filename and content of attachments. The whole message is capped at 5 MiB (see Limits and errors); that cap includes the Base64-encoded attachment content.

contentstring

Content of an attached file, passed as a Base64 string.

filenamestring

Name of attached file. When omitted, empty or null — an unnamed inline image, for example — the file is sent as attachment.

pathstring

URL where the attachment file is hosted.

contentTypestring

Content type for the attachment, if not set will be derived from the filename property.

contentIdstring

Content ID for inline images. Use with <img src="cid:..."> in your HTML.

tagsarray

Custom data passed in key/value pairs.

namestringrequired

The name of the email tag.

It can only contain ASCII letters (a–z, A–Z), numbers (0–9), underscores (_), or dashes (-). Max 256 characters.

valuestringrequired

The value of the email tag.

It can only contain ASCII letters (a–z, A–Z), numbers (0–9), underscores (_), or dashes (-). Max 256 characters.

Headers

Idempotency-Keystringheader

Add an idempotency key to prevent duplicated emails.

Should be unique per API request
Idempotency keys expire after 24 hours
Have a maximum length of 256 characters

Limits and errors

Recipients: at most 50 addresses across to, cc and bcc. More is refused with 400 validation_error.
Message size: at most 5 MiB for the whole message — subject, HTML, text, headers and Base64-encoded attachment content. An attachment supplied by path is not counted at request time, because its bytes are fetched later. A larger message is refused with 400 validation_error.
Monthly quota: counted per address. When the organization's remaining allowance cannot cover the request, the whole request is refused with 403 monthly_quota_exceeded; nothing in it is sent.
Daily limit: free organizations are limited to 100 emails a day. Paid organizations are limited to 100 a day for their first 7 days without a verified domain, 1,000 a day for their first 7 days with a verified domain or from day 7 through day 30, and have no daily limit after 30 days. Over the limit: 429 daily_quota_exceeded.
Rate limit: requests are limited per API key and organization. A request that reaches the rate limiter carries ratelimit-limit, ratelimit-remaining and ratelimit-reset (seconds) — requests refused earlier (validation, quota) may not; a rate-limited request returns 429 rate_limit_exceeded with retry-after (seconds).

Response Fields

idstring

The ID of the newly created email.

// Set RESEND_BASE_URL=https://api.postflare.dev in the environment before
// the process starts. Without it the SDK sends to api.resend.com, silently.
import { Resend } from 'resend';

const resend = new Resend('sk_xxxxxxxxx');

const { data, error } = await resend.emails.send({
  from: 'Acme <onboarding@resend.dev>',
  to: ['delivered@resend.dev'],
  subject: 'hello world',
  html: '<p>it works!</p>',
  replyTo: 'onboarding@resend.dev',
});

import resend

resend.api_key = "sk_xxxxxxxxx"
resend.api_url = "https://api.postflare.dev"

params: resend.Emails.SendParams = {
  "from": "Acme <onboarding@resend.dev>",
  "to": ["delivered@resend.dev"],
  "subject": "hello world",
  "html": "<p>it works!</p>",
  "reply_to": "onboarding@resend.dev"
}

email = resend.Emails.send(params)
print(email)

curl -X POST 'https://api.postflare.dev/emails' \
  -H 'Authorization: Bearer sk_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <onboarding@resend.dev>",
    "to": ["delivered@resend.dev"],
    "subject": "hello world",
    "html": "<p>it works!</p>",
    "reply_to": "onboarding@resend.dev"
  }'

Response

{
  "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
}