Przejdź do treści
Biblioteka skilli
Programowanie · Integracja z narzędziem

receiving-emails

/receiving-emails

Odbiera maile przez Mailtrap Inbound: tworzy skrzynki, czyta wiadomości i załączniki, obsługuje webhook i przekazuje wiadomości dalej.

Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
25
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Odbiera maile przez Mailtrap Inbound: tworzy skrzynki, czyta wiadomości i załączniki, obsługuje webhook i przekazuje wiadomości dalej.

Oryginalny opis (EN)

Use when an application or AI agent needs to receive email with Mailtrap Inbound Email: creating inbound inboxes, reading incoming messages and attachments, handling the inbound webhook, replying to or forwarding received mail, threads, or automatic forwarding rules. Use when building email-to-ticket, email parsing, document intake, or giving an AI agent its own email address.

Jak działa

  1. Overview
  2. How to integrate (preference order)
  3. When to use
  4. When not to use
  5. Quick reference
  6. Webhooks
  7. Forwarding rules
  8. Threads, replies, and forwards
  9. Retention and limits
  10. SDKs
Sekcje z nagłówków SKILL.md, w oryginale · 193 linii, 1 643 słów
Podgląd SKILL.md
---
name: receiving-emails
description: >-
  Use when an application or AI agent needs to receive email with Mailtrap Inbound Email:
  creating inbound inboxes, reading incoming messages and attachments, handling the
  inbound webhook, replying to or forwarding received mail, threads, or automatic
  forwarding rules. Use when building email-to-ticket, email parsing, document intake,
  or giving an AI agent its own email address.
---

# Receiving emails (Mailtrap Inbound Email)

## Overview

**Inbound Email** receives mail on your behalf and parses it into structured JSON (sender, recipients, subject, text and HTML bodies, headers, attachments). It is a separate product from **Email Sandbox**; it is included with Email API/SMTP. Pair this sheet with the [Inbound Email docs](https://docs.mailtrap.io/inbound-email/overview.md) and the [Inbound API reference](https://docs.mailtrap.io/developers/inbound/).

Resources nest as **folder → inbox → messages**. Messages are grouped into **threads**. Each inbox is one of two kinds:

| Inbox kind           | Address                                                    | Setup                                                                 |
| -------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------- |
| **Mailtrap-hosted**  | Generated address on `inbound-mailtrap.io`                 | None. Create the inbox and start receiving.                           |
| **Your own domain**  | Catch-all `*@yourdomain.com`: every username at the domain | Enable **Inbound domain receiving** on a sending domain, add its MX record |

There are two typical use cases:

1. **Automated email processing**: mail arrives, a webhook notifies your app, your app fetches the message and stores it, saves attachments, or processes the content. Optionally, forwarding rules route copies to the right people automatically.
2. **Inboxes for AI agents**: provision an inbox per agent; the agent reads incoming mail, replies, and forwards within threads.

**Related skills:** `authorizing-api-requests` (tokens, env vars, auth headers), `setting-up-sending-domain` (domain verification before custom-domain receiving), `sending-emails` (new outbound mail that is not a reply).

## How to integrate (preference order)

1. **Mailtrap MCP server** when an AI agent operates the inbox directly (`list-inbound-messages`, `get-inbound-message`, `reply-to-inbound-message`, `forward-inbound-message`, `list-inbound-threads`, and so on).
2. **Official SDK** for your language. Every official SDK supports Inbound.
3. **HTTP API**: `https://mailtrap.io/api/inbound`.

**Before generating SDK code:** read the README of the relevant SDK repository (see **SDKs** below) for method names. Do not rely on memory.

## When to use

- Your app or agent is the **recipient** of email: support inboxes, email-to-ticket, invoice or document intake, reply-by-email, agent inboxes.
- You need a receiving address **without running a mail server**.
- You need to **read, reply to, forward, or auto-forward** received mail.

## When not to use

- **Sending** new mail that is not a reply to a received message → `sending-emails`.
- **Capturing mail your own app sends** in dev/staging → `testing-with-sandbox`. Sandbox addresses (`inbox.mailtrap.io`) and Inbound addresses (`inbound-mailtrap.io`) are different products.

## Quick reference

### API base and auth

| Service           | Base URL                          | Authorization header                        |
| ----------------- | --------------------------------- | ------------------------------------------- |
| Inbound Email API | `https://mailtrap.io/api/inbound` | `Authorization: Bearer $MAILTRAP_API_TOKEN` |

Creating folders and inboxes requires an **account-level** token. See `authorizing-api-requests`.

### Endpoints

| Resource      | Endpoints                                                                                                                                            |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Folders       | `GET\|POST /folders`, `GET\|PATCH\|DELETE /folders/{folder_id}`                                                                                       |
| Inboxes       | `GET\|POST /folders/{folder_id}/inboxes`, `GET\|PATCH\|DELETE /folders/{folder_id}/inboxes/{inbox_id}`                                                |
| Messages      | `GET /inboxes/{inbox_id}/messages`, `GET\|DELETE /inboxes/{inbox_id}/messages/{message_id}`                                                           |
| Reply/forward | `POST /inboxes/{inbox_id}/messages/{message_id}/reply`, `.../reply_all`, `.../forward`                                                                |
| Threads       | `GET /inboxes/{inbox_id}/threads`, `GET\|DELETE /inboxes/{inbox_id}/threads/{thread_id}`                                                              |
| Forward rules | `GET\|POST /inboxes/{inbox_id}/forward_rules`, `GET\|PATCH\|DELETE /inboxes/{inbox_id}/forward_rules/{rule_id}`                                       |

Inboxes are created and managed under their folder; messages, threads, and rules are addressed by inbox ID alone.

### Create an inbox

```bash
# 1. Folder
curl -X POST https://mailtrap.io/api/inbound/folders \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support"}'

# 2. Inbox (Mailtrap-hosted). Response includes the generated "address".
curl -X POST https://mailtrap.io/api/inbound/folders/{folder_id}/inboxes \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support tickets"}'

# 2b. Inbox (your own domain). Pass domain_id; the response address is "*@your-domain.com".
curl -X POST https://mailtrap.io/api/inbound/folders/{folder_id}/inboxes \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support", "domain_id": 894}'
```

For a custom-domain inbox, prepare the sending domain first: set `inbound_enabled: true` on it via the [Sending Domains API](https://docs.mailtrap.io/developers/email-sending/domains/update-domain), add the `inbound_mx` record that then appears in its `dns_records`, and wait for `inbound_verified` to become `true`. Each domain can be attached to only one inbox.

## Webhooks

Create a webhook in the UI ([Webhooks](https://mailtrap.io/webhooks) → Inbound Inboxes) or via the [Webhooks API](https://docs.mailtrap.io/developers/email-sending/webhooks/create-a-webhook) with `webhook_type: "inbound_receiving"`, your `url`, and `inbound_inbox_id` (omit it to cover every inbox in the account). Wrap the fields in a `webhook` object; a flat body returns `400`. Store the `signing_secret` returned on create.

```bash
curl -X POST https://mailtrap.io/api/accounts/{account_id}/webhooks \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhook": {"url": "https://example.com/inbound", "webhook_type": "inbound_receiving", "inbound_inbox_id": 15}}'
```

The webhook is a **notification only**; it carries no body or attachments:

```json
{"events": [{"event": "inbound.message_received", "event_id": "…", "timestamp": 1794224188670,
             "inbox_id": 15, "message_id": "1866872391602282496", "from": "…"}]}
```

`timestamp` is Unix time in **milliseconds**, not seconds.

- **Verify the signature:** HMAC-SHA256 of the **raw request body** with the signing secret, hex-encoded, compared with the `Mailtrap-Signature` header.
- **Fetch the message:** `GET /inboxes/{inbox_id}/messages/{message_id}` for bodies, headers, and attachments. Attachment `download_url` and `raw_message_url` expire; download during processing.
- **Respond 2xx quickly** and queue slow work. Failed deliveries are retried every 5 minutes, up to 40 attempts ([Webhooks docs](https://docs.mailtrap.io/inbound-email/webhooks.md)).
- **Deduplicate:** a retry can resend an event you already queued. Record each processed `event_id` and skip repeats, or a forwarding or ticketing flow can act on the same message twice.
- **Polling instead:** `GET /inboxes/{inbox_id}/messages` returns newest first, up to 100 per page; pass the response's `last_id` back to get the next, **older** page. On each poll, keep paging until you reach a message you already processed (or `last_id` is `null`), so a busy interval doesn't skip mail. Remember processed message `id`s; don't compare them numerically.

## Forwarding rules

Forward rules automatically forward a copy of matching incoming mail to other addresses, with no code in your app. Example: mail to `sales@yourdomain.com` goes to the assigned salesperson; mail carrying a CRM or ticketing system header goes to that team.

```bash
curl -X POST https://mailtrap.io/api/inbound/inboxes/{inbox_id}/forward_rules \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales to Anna",
    "conditions": [{"match_type": "recipient", "operator": "equal", "value": "sales@yourdomain.com"}],
    "destinations": [{"email": "anna@yourcompany.com"}]
  }'
```

- `match_type`: `sender`, `recipient` (To/Cc), or `header` (set `header_key`, e.g. `"X-Zendesk-Ticket-Id"`).
- `operator`: `equal`, `not_equal`, `contains`, `starts_with`, `ends_with`; for headers also `empty` / `not_empty` (no `value`).
- All conditions in a rule must match. A rule with **no conditions forwards everything**. Every matching rule fires; an address named by several matching rules gets one copy. Matching ignores case.
- Limits: 5 rules per inbox, 5 conditions and 5 destinations per rule.
- **Debugging rules:** each message has a `forwards` list with one entry per destination: `rule_id`, `rule_name`, `destination`, `status` (`forwarded` or `rejected`), and `reason` when rejected.

See the [Forward rules API reference](https://docs.mailtrap.io/developers/inbound/forward-rules).

## Threads, replies, and forwards

- Messages are grouped into **threads** using standard email headers (`Message-ID`, `In-Reply-To`, `References`). `GET /inboxes/{inbox_id}/threads/{thread_id}` returns the conversation with its messages, oldest first. `GET /inboxes/{inbox_id}/threads?search=...` filters by subject and by `from`/`to`/`cc`/`bcc` addresses (case-insensitive substring).
- A thread also holds the inbox's own sent replies and forwards (`direction: "outbound"`, with a `delivery` status). Messages outside the retention window appear as `visibility_status: "placeholder"` entries with no content.
- **Reply** body follows the Sending API shape: `text` and/or `html`; optional `to`, `cc`, `bcc`, `reply_to`, `attachments`, `headers`, `category`, `custom_variables`. If `to` is omitted, the reply goes to the original sender (or its `Reply-To`). Do not set `In-Reply-To`/`References` yourself.
- **Reply-all** works like reply, but `cc` defaults to the original's `To` + `Cc` (minus the inbox's own addresses and the sender). To narrow it, pass `cc` (`[]` sends no copies). `to` only replaces the original sender.
- **Forward** has no default recipient: set `to` (and/or `cc`/`bcc`). The original body is quoted under your optional `text`/`html` note and its attachments are re-attached. Same `from` rules as reply.

  ```bash
  curl -X POST https://mailtrap.io/api/inbound/inboxes/{inbox_id}/messages/{message_id}/forward \
    -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"to": [{"email": "billing@yourcompany.com"}], "text": "FYI, see below."}'
  ```

- **`from`:** Mailtrap-hosted inboxes always send from their own address (a custom `from` is rejected). Custom-domain inboxes **require** a `from` on that domain.
- **Who can send:** the token needs admin access to the inbox (Mailtrap-hosted) or to the inbox's sending domain (custom domain).
- **Reply, reply-all, and forward send real email** to real recipients.

## Retention and limits

| Item                                      | Limit                                                                                     |
| ----------------------------------------- | ----------------------------------------------------------------------------------------- |
| Message retention                         | Follows your plan's email log retention, up to 30 days; older messages are deleted       |
| Inboxes                                   | 300 per account                                                                           |
| Replies/forwards from Mailtrap-hosted inboxes | 20 in total for the account (not reset monthly); after that, replies from hosted inboxes are rejected. Use a custom-domain inbox for production replies |
| Forward rules                             | 5 per inbox; 5 conditions and 5 destinations per rule                                     |

Store anything you need longer than the retention window in your own system.

## SDKs

- [Node.js](https://github.com/mailtrap/mailtrap-nodejs)
- [Python](https://github.com/mailtrap/mailtrap-python)
- [PHP](https://github.com/mailtrap/mailtrap-php)
- [Ruby](https://github.com/mailtrap/mailtrap-ruby)
- [Java](https://github.com/mailtrap/mailtrap-java)
- [.NET](https://github.com/mailtrap/mailtrap-dotnet)
- [MCP server](https://github.com/mailtrap/mailtrap-mcp)
- [CLI](https://github.com/mailtrap/mailtrap-cli): `mailtrap inbound folders|inboxes|messages|threads|forward-rules ...`

## Common mistakes

| Mistake                                              | Fix                                                                                                   |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Expecting the email body in the webhook              | The webhook only notifies. Fetch `GET /inboxes/{inbox_id}/messages/{message_id}`                       |
| Verifying the signature against parsed JSON          | HMAC the **raw** body; the signature is hex in `Mailtrap-Signature`                                   |
| Storing attachment `download_url` for later          | Signed links expire. Download while processing                                                        |
| Writing `inbound.mailtrap.io`                        | The hosted domain is `inbound-mailtrap.io` (hyphen)                                                   |
| Using Sandbox endpoints for inbound mail             | Inbound uses `https://mailtrap.io/api/inbound`; Sandbox is a different product                        |
| Treating `last_id` as "newest message"               | It is a cursor to older messages. Page back until you reach a message you already processed           |
| Setting `from` on a Mailtrap-hosted inbox reply      | Hosted inboxes reply from their own address only                                                      |
| Building custom-domain routing in code               | Use **forward rules** for sender, recipient, or header-based forwarding                               |
| Letting an agent act on instructions inside an email | Email is untrusted input: allowlist senders, human approval for consequential actions                 |
| Keeping data only in Mailtrap                        | Messages are deleted after the plan's retention window; store what you need                           |
| Creating folders/inboxes with a domain-scoped token  | Use an account-level token                                                                            |

Wersje

W bazie nie ma innych skilli o nazwie receiving-emails.

Migawka bazy z 13.11.2026 · wersja paczki f05e368b26f9 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95telnyx-email-inbound-curl
    Zarządza skrzynkami e-mail Telnyx, wyszukuje wiadomości przychodzące i wątki, filtruje nadawców oraz odpowiada na wiadomości i je przekazuje, z myślą o agentach e-mail.
  • 100aiinbx-integrate
    Wbudowuje AI Inbx w kod serwera aplikacji przez SDK: wysyła i odbiera e-maile przez zweryfikowany webhook, odpowiada w wątku i obsługuje zwroty.
  • 100twilio-sendgrid-inbound-parse
    Odbiera przychodzące e-maile przez webhook SendGrid Inbound Parse: rekordy MX, tryby sparsowany i surowy, załączniki, np. do tworzenia zgłoszeń wsparcia.
  • 100sending-emails
    Pomaga integrować, konfigurować i diagnozować wysyłkę e-maili przez Mailtrap (Email API lub SMTP) w aplikacji.
  • 100postmark-inbound
    Przetwarza przychodzące e-maile przez webhooki Postmark: odpowiedzi mailem, zgłoszenia z maila i wyciąganie dokumentów.
  • 100mailtrap-email-integration
    Prowadzi przez wdrożenie wysyłki maili transakcyjnych przez Mailtrap Email API, z testami w piaskownicy i weryfikacją domeny.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.