Send email

Send emails programmatically via our API.

POST /v1/send-email

Request body

The request body should be a JSON object with the following parameters:

Parameter	Type	Required	Description
from	string		Email address of the sender.
to	string		Email address of the recipient.
subject	string		Subject line of the email.
html	string	-	HTML content of the email. Required if text is not provided.
text	string	-	Plain text content of the email. Required if html is not provided.

Tip

You must provide at least one of html or text.

Example request

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Your Subject Here",
  "html": "<h1>Hello World</h1><p>This is the HTML content.</p>",
  "text": "Hello World\nThis is the plain text content."
}

Responses

Success (202 Accepted)

Indicates the email has been successfully queued for sending.

{
  "success": true,
  "message": "Email queued for sending"
}

Error (400 Bad Request)

Indicates invalid parameters in the request body. The message field provides details about the specific validation errors.

{
  "success": false,
  "message": "`to` is invalid. `subject` can't be blank"
}

Error (401 Unauthorized)

Indicates an invalid or missing API key.

{
  "success": false,
  "message": "Invalid or missing API key"
}

Error (402 Payment Required)

Indicates an issue with the subscription or usage limits. The error field provides more details.

{
  "success": false,
  "message": "Subscription expired",
  "error": "Your subscription has expired. Please renew your subscription to continue sending emails. Go to https://app.usepoodle.com/upgrade to renew your subscription."
}

{
  "success": false,
  "message": "Trial limit reached",
  "error": "Your free trial emails have been used up. Please upgrade to a paid plan to continue sending emails. Go to https://app.usepoodle.com/upgrade to upgrade your plan."
}

{
  "success": false,
  "message": "Monthly limit reached",
  "error": "Monthly email limit reached. Please upgrade your plan to send more emails. Go to https://app.usepoodle.com/upgrade to upgrade your plan."
}

Error (403 Forbidden)

Indicates the account is suspended, often due to high bounce or complaint rates. The error field provides more details.

{
  "success": false,
  "message": "Account suspended",
  "error": "Your account is suspended due to a high bounce rate (15%). Please contact support." // Example message
}

Error (422 Unprocessable Entity)

Indicates an internal error occurred. This should be rare, but the error field might provide more context.

{
  "success": false,
  "message": "Failed to queue email",
  "error": "Internal error details" // Optional
}

Error (429 Too Many Requests)

Indicates the rate limit has been exceeded. Check the retry-after HTTP header for guidance on when to retry.

{
  "success": false,
  "message": "Rate limit exceeded",
  "error": "Too many requests. Try again after 1 second." // Example message
}