Email

Send an email from one of your templates to one address, from your own domain, paid from your Ponitor balance. Each request is one email, and most leave within seconds.

Before you send

You set up email once, in the app. The API sends what you set up there.

1. Add your domain under Email › Domains, such as mail.example.com, and add the DNS records it shows at your DNS provider. Ponitor checks them and marks the domain verified.
2. Add a sender on the domain, such as hello@mail.example.com, with the name inboxes show. Make one sender the default.
3. Set your brand under Email › Brand: your logo, colours and footer. Every email uses it.
4. Write a template under Email › Templates. Each template has a handle, such as verification-code, and can use {{variables}} in its subject and body.

Try a template from its editor with Send Test before your system sends it.

How a send works

A request names a template by its handle and gives a value for each of its variables:

{
  "to": "ada@example.com",
  "template": "verification-code",
  "values": { "first_name": "Ada", "code": "482913", "expires_in": "10 minutes" },
  "externalId": "signup-8812"
}

• Ponitor fills in the values, draws the email with your brand, and sends it to to. One request sends to one address.
• It goes from your default sender. To send from another, put its address in from, such as billing@mail.example.com.
• Every variable the template uses needs a value. A request without one is refused, and nothing is charged.
• Your externalId is unique within your team. Send a request again with the same externalId, after a timeout for example, and you get the first email back. You're charged once. See Retries and externalId.

Charges and refunds

• Ponitor charges your team's price per email when it accepts the request. The email's cost shows it.
• An email that couldn't be sent is FAILED, and its cost goes back to your account.
• An email that was sent but BOUNCED, because the address doesn't exist or wouldn't take it, isn't refunded.

What happens to an email

Status	What it means
QUEUED	Charged and waiting to go out.
SENT	On its way to the inbox.
DELIVERED	The recipient's mail server accepted it.
DELAYED	The recipient's mail server hasn't taken it yet. It's tried again.
BOUNCED	The address doesn't exist or wouldn't take it. Not refunded.
COMPLAINED	The recipient marked it as spam.
FAILED	It couldn't be sent. Its cost was refunded, and failureReason says why.

Follow an email with Get an email, or with the email.* webhook events.

When sending is paused

Mail servers judge your domain by how many of your emails bounce or are marked as spam. If too many of your team's do, Ponitor pauses your team's email sending to protect your domain and every other team's. While it's paused, every send is refused with 403 (E02017) and nothing is charged. Contact us to resume it.

To keep bounces and complaints low, send only to people who asked for your emails, and stop sending to an address that bounced.

Sandbox and live

	Sandbox	Live
Base URL	https://sandbox-api.ponitor.com/email/v1	https://api.ponitor.com/email/v1
Domains	Verified at their first check, with no DNS changes	Verified once their DNS records are found
Emails	Never delivered to an inbox. Test addresses give each outcome, and any other address stays SENT	Sent to the inbox
Sending paused	Never by bounces or spam reports	When too many bounce or are marked as spam
Paid from	Your test balance	Your account balance

The endpoints

Endpoint	What it does
POST /emails	Sends an email from one of your templates to one address.
GET /emails/{id}	Gets an email and everything that happened to it.

Email belongs to your team, not to a workspace. A request that names a workspace is refused.