# Introduction

Prontuno is a transactional email API for sending email, managing sending domains, monitoring delivery, and keeping team-level suppression lists. It uses a JSON API over HTTPS and processes email asynchronously so your application does not have to wait for an SMTP delivery attempt to finish.

## Base URL

```
https://api.prontuno.net/v1
```

Endpoint paths in the API reference are relative to this URL. For example, `/emails` means `https://api.prontuno.net/v1/emails`.

## What you can build

- Send a transactional email to one or more recipients.
- Submit multiple independent emails in a batch.
- Track each recipient’s message and delivery status.
- Add sending domains and inspect their DNS verification records.
- Create and manage suppressions that prevent unwanted sends.

Every API key belongs to one team. Messages, domains, suppressions, credit usage, and request limits are isolated to that team.

## Before your first request

1. Create a Prontuno API key for your team.
2. Give the key only the scopes your integration needs. A sending integration needs `email:send`.
3. Make sure the key has a sending domain.
4. Store the key in a server-side environment variable or secret manager.

API keys are secrets. Do not place one in browser code, a mobile app, a public repository, or a URL.

## Send your first email

Set your API key in the environment, then submit a JSON request:

```
export PRONTUNO_API_KEY="pno_sk_YOUR_KEY"

curl --request POST https://api.prontuno.net/v1/emails \
    --header "Authorization: Bearer ${PRONTUNO_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
    --data '{
        "from": "Your App <hello@example.com>",
        "to": "customer@example.net",
        "subject": "Welcome to Your App",
        "text": "Thanks for signing up.",
        "html": "<p>Thanks for signing up.</p>"
    }'
```

A successful request returns HTTP `202 Accepted`:

```
{
    "emails": [
        {
            "id": "email_01kxwz4bfhe00rr3ww02remnap",
            "to": "customer@example.net"
        }
    ]
}
```

`202 Accepted` means Prontuno durably accepted the request for asynchronous processing. It does not mean the message has reached the recipient’s mailbox. Keep the returned `email_...` identifier and use it to check delivery status.

## Core API conventions

- **HTTPS only:** Send production requests to the HTTPS base URL.
- **JSON:** Requests with a body must use `Content-Type: application/json`. Responses use JSON.
- **Asynchronous sending:** Send operations return `202` after acceptance and continue in the background.
- **One record per recipient:** A request containing `to`, `cc`, or `bcc` recipients returns a separate email ID for each recipient. Their delivery outcomes may differ.
- **Opaque identifiers:** Treat identifiers such as `email_...`, `dom_...`, and `sup_...` as case-sensitive opaque strings.
- **UTC timestamps:** API timestamps use ISO 8601 UTC values, such as `2026-07-14T19:43:25.000Z`.
- **Request IDs:** Every response includes an `x-request-id` header. Record it when troubleshooting or contacting support.
- **Request size:** JSON request bodies are limited to 15 MB. Base64 encoding increases attachment size, so the usable raw attachment capacity is approximately 11 MB per request.

## Designing a reliable integration

Use a unique `Idempotency-Key` for every logical send, keep the request body unchanged when retrying, and inspect the structured `error.retryable` field before retrying a failed API request. Respect `Retry-After` and `RateLimit-*` response headers when present.

For help with an API request, contact [Prontuno Support](https://prontuno.com/contact/) or email [support@prontuno.com](mailto:support@prontuno.com). Include the response’s `x-request-id`, but never include your API key.