Hopp til innholdet
Agdir Email Programmerbar e-post for utviklere · fra Agdir

Dokumentasjon

Send din første e-post på noen minutter, og slå deretter opp alle endepunktene i REST-API-et.

Kom i gang

  1. Legg til og verifiser domenet ditt

    Legg til domenet du sender fra i dashbordet, og publiser DKIM- og SPF-postene som vises. Vi sjekker DNS automatisk; på Cloudflare kan vi legge inn postene for deg.

    Åpne Domener →

  2. Opprett en API-nøkkel

    Full tilgang for backend, eller kun sending (eventuelt begrenset til ett domene) for apper og AI-agenter. Nøkkelen vises én gang.

    Åpne API-nøkler →

  3. Send en e-post

    Installer Node.js-SDK-en, eller kall REST-API-et fra hvilket som helst språk. SDK-er for Python, PHP, Go, .NET, Ruby, Rust og en CLI finnes på GitHub.

    Alle SDK-er på GitHub →
    send.ts
    // npm install @agdirlabs/email
import { AgdirEmail } from '@agdirlabs/email';

const agdir = new AgdirEmail('re_xxxxxxxxx');

const { id } = await agdir.emails.send({
  from: 'Acme <hello@yourdomain.com>',
  to: 'you@example.com',
  subject: 'Hello from agdir.email',
  html: '<p>It works! 🎉</p>'
});
    cURL
    curl -X POST https://api.agdir.email/emails \
  -H 'Authorization: Bearer re_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["you@example.com"],
    "subject": "Hello from agdir.email",
    "html": "<p>It works!</p>"
  }'

  4. Følg leveringen

    Hendelsene for hver e-post (sendt, levert, avvist, klage, åpnet, klikket) vises i dashbordet. For å motta dem i appen din legger du til en webhook: hendelsene signeres etter Standard Webhooks, og SDK-ene verifiserer signaturen for deg.

    Se webhook-hendelser →

Bruk det fra AI-agenter (MCP)

MCP-serveren på api.agdir.email/mcp lar agenter sende e-post og administrere domener, sperrelister og webhooks med en avgrenset nøkkel. Med Claude Code:

Claude Code
claude mcp add --transport http agdir-email https://api.agdir.email/mcp --header "Authorization: Bearer re_xxxxxxxxx"

API-grunnleggende

API-grunnleggende og referansen nedenfor er på engelsk. Maskinlesbar beskrivelse: openapi.json · openapi.yaml

Authentication

Every request carries an API key as a bearer token: Authorization: Bearer re_…. Create keys in the dashboard at https://app.agdir.email. A key has one of two permissions:

  • full_access — every operation.
  • sending_access — only POST /emails and POST /emails/batch (optionally limited to one domain). Other operations answer 401 restricted_api_key.

Each operation states the permission it needs in its description and in the x-required-permission extension.

A missing or malformed Authorization header answers 401 missing_api_key; an unknown key answers 403 invalid_api_key.

Requests and responses

Bodies are JSON with snake_case fields. Timestamps are ISO 8601 strings in UTC. A body that is not valid JSON answers 400 validation_error.

Errors

Errors have a JSON body {"statusCode": 422, "name": "validation_error", "message": "…"} (see the Error schema). name is a stable machine-readable code; message is for humans.

name status meaning
missing_api_key 401 No bearer token.
restricted_api_key 401 A sending_access key was used for another operation.
invalid_api_key 403 Unknown or revoked key.
validation_error 400 / 403 / 422 Invalid request (422), invalid JSON (400), or an account-state refusal such as an unverified sender domain, a paused team or the plan's domain limit (403).
not_found 404 No such resource in this team.
invalid_idempotent_request 409 Idempotency key reused with a different body.
concurrent_idempotent_requests 409 Idempotency key reused while the first request is still running.
daily_quota_exceeded 429 Daily sending cap reached. Do not retry until the next UTC day.
monthly_quota_exceeded 429 Monthly allowance or spend limit reached. Do not retry.
rate_limit_exceeded 429 Too many requests per second; retry after retry-after seconds.
internal_server_error 500 Unexpected error; safe to retry idempotent requests.

Rate limits

Requests are limited per team (all keys share the budget), by default 10 requests per second in a fixed 1-second window. Authenticated responses carry ratelimit-limit, ratelimit-remaining and ratelimit-reset (seconds until the window resets). When the limit is exceeded the API answers 429 rate_limit_exceeded with a retry-after header.

Idempotency

POST /emails and POST /emails/batch accept an Idempotency-Key header (any string, unique per logical send, e.g. a UUID). For 24 hours a repeated key with the same body returns the original response without sending again; the same key with a different body answers 409 invalid_idempotent_request.

Pagination

List operations return {"object": "list", "has_more": bool, "data": […]}, newest first. Pass limit (1–100) and, for the next page, after = the id of the last item of the previous page. before is not supported.

Webhooks

Email events are POSTed to your endpoints as JSON (see the emailEvent webhook), signed according to the Standard Webhooks specification.

API-referanse

Base URL https://api.agdir.email · v1.0.0

Emails

Send single emails or batches, read their status and cancel scheduled ones.

Send an email

POST /emails

Tilgang kun sending

Accepts one email for delivery (or for later delivery when scheduled_at is set) and returns its id. The from domain must be a verified domain of your team. At most 50 recipients across to, cc and bcc. Recipients on the team's suppression list are dropped; if every recipient is suppressed the email is stored with status failed and nothing is sent.

Permission: full_access or sending_access.

Parametere

  • Idempotency-Key header · string
    Makes the request safe to retry: for 24 hours a repeated key with the same body returns the original response without sending again. Reusing a key with a different body answers 409 invalid_idempotent_request.

ForespørselsinnholdSendEmailRequest

An email. Either html or text (or both) is required.

  • from string påkrevd
    user@example.com or Display Name <user@example.com>.
  • to string | array of string påkrevd
    One address or a non-empty array of addresses.
  • subject string påkrevd
  • html string
    HTML body.
  • text string
    Plain-text body.
  • cc string | array of string
    One address or a non-empty array of addresses.
  • bcc string | array of string
    One address or a non-empty array of addresses.
  • reply_to string | array of string
    One address or a non-empty array of addresses.
  • headers object
    Extra email headers.
  • tags array of Tag
  • scheduled_at string (date-time)
    Send later: an ISO 8601 timestamp with a UTC offset, in the future and at most 72 hours ahead. The email's status is scheduled until then; it can be canceled.

Svar

200
Email accepted.
400
The body is not valid JSON (validation_error).
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
invalid_api_key, or validation_error for an account-state refusal: the sender domain is not verified for this team, the key is limited to another domain, or sending is paused/suspended for the team.
409
invalid_idempotent_request or concurrent_idempotent_requests.
422
The request is invalid (validation_error). message names the offending field.
429
rate_limit_exceeded (retry after retry-after seconds), or a quota refusal that must not be retried: daily_quota_exceeded (until the next UTC day) or monthly_quota_exceeded (monthly allowance or spend limit reached).
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X POST https://api.agdir.email/emails \
  -H 'Authorization: Bearer re_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": [
      "user@example.org"
    ],
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up!</p>"
  }'

Send a batch of emails

POST /emails/batch

Tilgang kun sending

Accepts 1–100 emails in one request. Each item has the same shape as POST /emails (scheduled_at included).

With x-batch-validation: strict (default) one invalid email rejects the whole batch, nothing is stored, and the error message is prefixed with the item index, e.g. [1] to: Invalid email address. With permissive the valid emails are accepted and the invalid ones are listed in errors.

The batch is checked against the daily/monthly quota as a whole (all or nothing).

Permission: full_access or sending_access.

Parametere

  • Idempotency-Key header · string
    Makes the request safe to retry: for 24 hours a repeated key with the same body returns the original response without sending again. Reusing a key with a different body answers 409 invalid_idempotent_request.
  • x-batch-validation header · "strict" | "permissive"
    strict (default): any invalid email rejects the whole batch. permissive: valid emails are accepted, invalid ones are reported in errors.

ForespørselsinnholdSendBatchRequest

Svar

200
Batch accepted.
400
The body is not valid JSON (validation_error).
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
invalid_api_key, or validation_error for an account-state refusal: the sender domain is not verified for this team, the key is limited to another domain, or sending is paused/suspended for the team.
409
invalid_idempotent_request or concurrent_idempotent_requests.
422
The request is invalid (validation_error). message names the offending field.
429
rate_limit_exceeded (retry after retry-after seconds), or a quota refusal that must not be retried: daily_quota_exceeded (until the next UTC day) or monthly_quota_exceeded (monthly allowance or spend limit reached).
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X POST https://api.agdir.email/emails/batch \
  -H 'Authorization: Bearer re_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "from": "Acme <hello@acme.com>",
      "to": [
        "alice@example.org"
      ],
      "subject": "Your receipt",
      "text": "Thanks, Alice!"
    },
    {
      "from": "Acme <hello@acme.com>",
      "to": [
        "bob@example.org"
      ],
      "subject": "Your receipt",
      "text": "Thanks, Bob!"
    }
  ]'
Svar
{
  "data": [
    {
      "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
    },
    {
      "id": "2b8d4a1e-6f5c-4b1a-9c3e-7d2f0a8b9c10"
    }
  ]
}

Retrieve an email

GET /emails/{email_id}

Tilgang full tilgang

Returns an email and its latest status (last_event).

Permission: full_access.

Parametere

  • email_id path · string (uuid) påkrevd
    Email id returned when the email was sent.

Svar

200
The email.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X GET https://api.agdir.email/emails/<email_id> \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Cancel a scheduled email

POST /emails/{email_id}/cancel

Tilgang full tilgang

Cancels an email whose status is scheduled; its status becomes canceled. Emails in any other status answer 422 validation_error.

Permission: full_access.

Parametere

  • email_id path · string (uuid) påkrevd
    Email id returned when the email was sent.

Svar

200
Email canceled.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
422
The request is invalid (validation_error). message names the offending field.
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X POST https://api.agdir.email/emails/<email_id>/cancel \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Domains

Sending domains — add a domain, publish its DNS records, verify it.

List domains

GET /domains

Tilgang full tilgang

Lists the team's domains, newest first. Without limit all domains are returned. List items do not include records; retrieve a domain for those.

Permission: full_access.

Parametere

  • limit query · integer
    Page size (1–100). Defaults to 100.
  • after query · string (uuid)
    Return items after this id (the id of the last item of the previous page).

Svar

200
A page of domains.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
422
The request is invalid (validation_error). message names the offending field.
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X GET https://api.agdir.email/domains \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Add a domain

POST /domains

Tilgang full tilgang

Adds a sending domain and returns the DNS records to publish: a DKIM TXT record (selector agdir), an MX and an SPF TXT record on the send subdomain (custom MAIL FROM) and a recommended DMARC TXT record. Record names are relative to the registrable domain (send for acme.com, send.mail for mail.acme.com). Verification starts immediately and is retried automatically for 72 hours.

A domain can belong to one team at a time. Consumer mailbox domains (gmail.com, …) are refused. Adding more domains than the plan includes answers 403 validation_error.

Permission: full_access.

ForespørselsinnholdCreateDomainRequest

  • name string påkrevd
    Domain or subdomain you own.
  • region "eu-north-1"
    Sending region. Only eu-north-1 is available.

Svar

200
Domain created.
400
The body is not valid JSON (validation_error).
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
invalid_api_key, or validation_error when the plan's domain limit is reached.
422
The request is invalid (validation_error). message names the offending field.
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X POST https://api.agdir.email/domains \
  -H 'Authorization: Bearer re_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "acme.com"
  }'

Retrieve a domain

GET /domains/{domain_id}

Tilgang full tilgang

Returns a domain with its DNS records and their verification status.

Permission: full_access.

Parametere

  • domain_id path · string (uuid) påkrevd
    Domain id.

Svar

200
The domain.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X GET https://api.agdir.email/domains/<domain_id> \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Delete a domain

DELETE /domains/{domain_id}

Tilgang full tilgang

Deletes the domain. Its queued and scheduled emails are marked failed.

Permission: full_access.

Parametere

  • domain_id path · string (uuid) påkrevd
    Domain id.

Svar

200
Domain deleted.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X DELETE https://api.agdir.email/domains/<domain_id> \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Verify a domain now

POST /domains/{domain_id}/verify

Tilgang full tilgang

Checks the domain's DNS records immediately instead of waiting for the automatic schedule, and restarts the 72-hour verification window of a failed domain. The check result is visible through GET /domains/{domain_id}.

Permission: full_access.

Parametere

  • domain_id path · string (uuid) påkrevd
    Domain id.

Svar

200
Check performed.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X POST https://api.agdir.email/domains/<domain_id>/verify \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Webhooks

Endpoints that receive signed email events.

List webhooks

GET /webhooks

Tilgang full tilgang

Lists the team's webhooks, newest first.

Permission: full_access.

Parametere

  • limit query · integer
    Page size (1–100). Defaults to 20.
  • after query · string (uuid)
    Return items after this id (the id of the last item of the previous page).

Svar

200
A page of webhooks.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
422
The request is invalid (validation_error). message names the offending field.
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X GET https://api.agdir.email/webhooks \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Create a webhook

POST /webhooks

Tilgang full tilgang

Registers an endpoint for the given event types and returns its signing secret. The endpoint must be an https URL without credentials whose host resolves only to public addresses (checked again before every delivery); redirects are not followed. A team can have at most 20 webhooks.

Permission: full_access.

ForespørselsinnholdCreateWebhookRequest

  • endpoint string (uri) påkrevd
    Public https URL.
  • events array of "email.sent" | "email.scheduled" | "email.delivered" | "email.delivery_delayed" | "email.complained" | "email.bounced" | "email.opened" | "email.clicked" | "email.failed" påkrevd
    Event types to deliver (duplicates are ignored).

Svar

200
Webhook created.
400
The body is not valid JSON (validation_error).
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
422
The request is invalid (validation_error). message names the offending field.
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X POST https://api.agdir.email/webhooks \
  -H 'Authorization: Bearer re_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "endpoint": "https://hooks.acme.com/agdir-email",
    "events": [
      "email.delivered",
      "email.bounced",
      "email.complained"
    ]
  }'

Retrieve a webhook

GET /webhooks/{webhook_id}

Tilgang full tilgang

Returns a webhook including its current signing secret.

Permission: full_access.

Parametere

  • webhook_id path · string (uuid) påkrevd
    Webhook id.

Svar

200
The webhook.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X GET https://api.agdir.email/webhooks/<webhook_id> \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Update a webhook

PATCH /webhooks/{webhook_id}

Tilgang full tilgang

Changes the endpoint, the subscribed events and/or the status. Fields left out are unchanged. Re-enabling a webhook that was disabled (by you, or automatically after three days of failed deliveries) clears its failure streak.

Permission: full_access.

Parametere

  • webhook_id path · string (uuid) påkrevd
    Webhook id.

ForespørselsinnholdUpdateWebhookRequest

  • endpoint string (uri)
    Public https URL.
  • events array of "email.sent" | "email.scheduled" | "email.delivered" | "email.delivery_delayed" | "email.complained" | "email.bounced" | "email.opened" | "email.clicked" | "email.failed"
  • status "enabled" | "disabled"

Svar

200
Webhook updated.
400
The body is not valid JSON (validation_error).
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
422
The request is invalid (validation_error). message names the offending field.
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X PATCH https://api.agdir.email/webhooks/<webhook_id> \
  -H 'Authorization: Bearer re_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "disabled"
  }'

Delete a webhook

DELETE /webhooks/{webhook_id}

Tilgang full tilgang

Deletes the webhook and its delivery log.

Permission: full_access.

Parametere

  • webhook_id path · string (uuid) påkrevd
    Webhook id.

Svar

200
Webhook deleted.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X DELETE https://api.agdir.email/webhooks/<webhook_id> \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Rotate the signing secret

POST /webhooks/{webhook_id}/signing-secret/rotate

Tilgang full tilgang

Generates a new signing secret. The old secret stops working immediately; deliveries from now on (including retries of earlier events) are signed with the new one.

Permission: full_access.

Parametere

  • webhook_id path · string (uuid) påkrevd
    Webhook id.

Svar

200
The new secret.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X POST https://api.agdir.email/webhooks/<webhook_id>/signing-secret/rotate \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Email event (sent to your endpoint)

POST Sendes av Agdir Email til endepunktet ditt.

Agdir Email POSTs one JSON event per request to each enabled webhook subscribed to its type. Respond with any 2xx status within 10 seconds; anything else (or a timeout) is retried after 5 s, 5 min, 30 min, 2 h, 5 h and 10 h. Deliveries are at least once: use webhook-id to deduplicate. A webhook that keeps failing for three days is disabled and the team owners are notified.

Verifying the signature (Standard Webhooks):

  1. Take the secret whsec_<base64> and base64-decode the part after whsec_ → key.
  2. Compute base64(HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<raw body>")).
  3. webhook-signature is a space-separated list of v1,<base64 signature>; accept the request if any v1 entry equals your signature (constant-time comparison).
  4. Reject the request if webhook-timestamp is more than 5 minutes away from now.

Always verify against the raw request body, before parsing it.

Parametere

  • webhook-id header · string (uuid) påkrevd
    Unique id of this delivery; the same on retries and replays.
  • webhook-timestamp header · string påkrevd
    Unix time (seconds) when this attempt was signed.
  • webhook-signature header · string påkrevd
    Space-separated v1,<base64 HMAC-SHA256> signatures.
  • user-agent header · string
    Always agdir.email-webhooks/1.0.

InnholdEmailEvent

The JSON body POSTed to webhook endpoints.

  • type "email.sent" | "email.scheduled" | "email.delivered" | "email.delivery_delayed" | "email.complained" | "email.bounced" | "email.opened" | "email.clicked" | "email.failed" påkrevd
    * email.scheduled — accepted with scheduled_at. * email.sent — handed to the mail transfer agent. * email.delivered — accepted by the recipient's mail server. * email.delivery_delayed — temporarily not deliverable; still retrying. * email.bounced — permanently rejected by the recipient's server. * email.complained — the recipient marked it as spam. * email.opened / email.clicked — engagement (when tracking is enabled). * email.failed — not sent (e.g. every recipient suppressed, domain deleted).
  • created_at string (date-time) påkrevd
    When the event happened.
  • data EmailEventData påkrevd

Svar

200
Any 2xx status acknowledges the event.
Innhold
{
  "type": "email.delivered",
  "created_at": "2026-10-30T10:00:05.000Z",
  "data": {
    "created_at": "2026-10-30T10:00:00.000Z",
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "message_id": "0100019a3f0e7c2b-5e1f3c1a-2b4d-4c6e-8f0a-1b2c3d4e5f60-000000",
    "from": "Acme <hello@acme.com>",
    "to": [
      "user@example.org"
    ],
    "subject": "Welcome to Acme",
    "tags": {
      "category": "welcome"
    }
  }
}

Webhook deliveries

The delivery log of a webhook: one webhook event per (webhook, email event), each with its HTTP attempts. Failed deliveries are retried after 5 s, 5 min, 30 min, 2 h, 5 h and 10 h; after that the event is failed. Any event can be replayed manually.

List deliveries

GET /webhooks/{webhook_id}/events

Tilgang full tilgang

Lists the webhook's deliveries (webhook events), newest first. A delivery is created for every email event the webhook is subscribed to while it is enabled.

Permission: full_access.

Parametere

  • webhook_id path · string (uuid) påkrevd
    Webhook id.
  • limit query · integer
    Page size (1–100). Defaults to 20.
  • after query · string (uuid)
    Return items after this id (the id of the last item of the previous page).

Svar

200
A page of deliveries.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
422
The request is invalid (validation_error). message names the offending field.
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X GET https://api.agdir.email/webhooks/<webhook_id>/events \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Retrieve a delivery

GET /webhooks/{webhook_id}/events/{event_id}

Tilgang full tilgang

Returns one delivery with the exact payload that is (or was) POSTed to the endpoint and the time of the next scheduled attempt.

Permission: full_access.

Parametere

  • webhook_id path · string (uuid) påkrevd
    Webhook id.
  • event_id path · string (uuid) påkrevd
    Delivery (webhook event) id — also the webhook-id header of its requests.

Svar

200
The delivery.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X GET https://api.agdir.email/webhooks/<webhook_id>/events/<event_id> \
  -H 'Authorization: Bearer re_xxxxxxxxx'

List delivery attempts

GET /webhooks/{webhook_id}/events/{event_id}/attempts

Tilgang full tilgang

Lists the HTTP attempts of one delivery, newest first.

Permission: full_access.

Parametere

  • webhook_id path · string (uuid) påkrevd
    Webhook id.
  • event_id path · string (uuid) påkrevd
    Delivery (webhook event) id — also the webhook-id header of its requests.
  • limit query · integer
    Page size (1–100). Defaults to 20.
  • after query · string (uuid)
    Return items after this id (the id of the last item of the previous page).

Svar

200
A page of attempts.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
422
The request is invalid (validation_error). message names the offending field.
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X GET https://api.agdir.email/webhooks/<webhook_id>/events/<event_id>/attempts \
  -H 'Authorization: Bearer re_xxxxxxxxx'

Replay a delivery

POST /webhooks/{webhook_id}/events/{event_id}/replay

Tilgang full tilgang

Queues one immediate, manual attempt of the delivery with the identical payload and webhook-id (signed with the current secret). It is not retried if it fails. Works for disabled webhooks too.

Permission: full_access.

Parametere

  • webhook_id path · string (uuid) påkrevd
    Webhook id.
  • event_id path · string (uuid) påkrevd
    Delivery (webhook event) id — also the webhook-id header of its requests.

Svar

200
Attempt queued.
401
missing_api_key (no bearer token) or restricted_api_key (a sending_access key used for an operation that needs full_access).
403
The API key is unknown or revoked (invalid_api_key).
404
No such resource in this team (not_found).
429
Too many requests per second (rate_limit_exceeded). Retry after retry-after seconds.
500
Unexpected server error (internal_server_error).
Forespørsel
curl -X POST https://api.agdir.email/webhooks/<webhook_id>/events/<event_id>/replay \
  -H 'Authorization: Bearer re_xxxxxxxxx'