# 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.
- Create and manage webhook endpoints, and rotate their signing secrets.
- Create, list, and revoke API keys and SMTP credentials.
- Download attachments from sent email.
- Read received email and its attachments, when receiving is enabled for your team.

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. Choose the narrowest [key type](https://prontuno.com/docs/sending/api-keys/) that does the job. A sending integration needs a Sending key.
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 32 MiB. Each email is limited to 25 MiB as sent, including headers, body, and base64-encoded attachments. Base64 adds about 37%, so one email can carry roughly 18 MiB of files.

## 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.