Quickstart

Welcome. This page walks you from "no account" to "delivered email" in five minutes. The rest of the docs go deeper on concepts, per-channel guides, SDKs, and the live API reference.

What you'll do

1. Create a workspace and connect a provider.
2. Mint a project API key.
3. Send a message with one curl.
4. Listen for delivery events.

1. Create a workspace

Sign in at app.dev.messagepipe.dev and create a workspace. You become the workspace owner automatically, and a default project named Production is provisioned for you (Workspaces, Projects).

2. Connect a provider

Open Settings → Providers and connect one of the supported backends. For this quickstart we'll use SendGrid for email:

provider_type:  sendgrid
channel:        email
credentials:    { "api_key": "SG.xxx" }

Your credentials are encrypted at rest the moment you save them. Plaintext never leaves your browser's POST body. See Providers for the full catalogue and how routing across multiple providers works.

3. Mint an API key

In Settings → API keys, click Create key, name it Quickstart, and give it the send scope. The secret is shown once, copy it now.

API keys begin with mp_live_ (production traffic) or mp_test_ (sandbox) and authenticate every call to the Send API.

4. Send your first message

curl https://api.dev.messagepipe.dev/v1/email/send \
  -H "Authorization: Bearer mp_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-$(uuidgen)" \
  -d '{
    "to": "you@example.com",
    "from": { "email": "hello@your-domain.com", "name": "Acme" },
    "subject": "Hello from MessagePipe",
    "html": "<p>It works!</p>"
  }'

from must be an object with an email — a bare string is rejected with a 400. You can omit it entirely once the project has a default sender configured.

A 202 Accepted response confirms the message has been queued. The body contains the canonical id (e.g. msg_06F4Y9CP1GQB39AA) you'll use to track delivery. Queued is not delivered — poll GET /v1/sends/{id}, where a failed send carries failure_code and failure_reason.

Idempotency is optional but strongly recommended. Provide a unique Idempotency-Key header (or an idempotency_key body field) so retries with the same key never produce duplicates. See Idempotency.

5. Listen for delivery

You have two choices:

• Webhooks: register an endpoint in Settings → Webhooks and MessagePipe will POST a signed JSON payload for every sent, delivered, bounced, failed event (Webhooks).
• Polling: GET /v1/sends/{id} returns the current status.

Where to next

• Concepts: the model: workspaces, projects, channels, templates.
• API reference: every endpoint, request, and response.
• Channel guides: per-channel pitfalls and tuning.
• SDKs: Node, Python, Go, and raw curl recipes.