Providers
The backends MessagePipe ships, and how routing across them works.
A provider configuration is one connected backend: a SendGrid API key, a Twilio account, an FCM service account. Connect one or more per channel and MessagePipe routes each send to the best one available.
Built-in catalogue
| Provider | Channels | Credentials |
|---|---|---|
sendgrid | api_key | |
mailgun | api_key, domain | |
ses | access_key_id, secret_access_key, region | |
smtp | host, port, username, password | |
resend | api_key | |
postmark | server_token | |
mailersend | api_key | |
zeptomail | send_mail_token, bounce_address | |
mailtrap | api_token | |
elasticemail | api_key | |
sparkpost (Bird email) | api_key | |
twilio | sms | account_sid, auth_token, from_number |
telnyx | sms | api_key, from_number |
bandwidth | sms | account_id, application_id, from_number, client_id, client_secret |
plivo | sms | auth_id, auth_token, sender_id |
sinch | sms | service_plan_id, api_token, sender_id |
vonage | sms | api_key, api_secret, sender_id |
bird_sms | sms | api_key, sender_id |
fcm | push | project_id, access_token |
apns | push | team_id, key_id, private_key, bundle_id |
whatsapp | chat | phone_number_id, access_token |
mock | every channel | mode (for tests) |
Routing
When the Send API picks a provider for a send, it ranks every active configuration that serves the requested channel by:
- Priority (lower wins, ties broken by health).
- Health status:
healthy›degraded›down. - Weight: among equal-priority healthy providers, traffic is split proportionally so you can canary a new vendor.
A provider can be attached to one project, from the provider's page or the project's
Providers tab (project_id on the provider). Only that project's sends use it; the
ranking above is applied to the providers a send is allowed to use, which are the project's
own and the workspace-wide ones. A provider with no project is workspace-wide and serves
every project. This also holds for a preferred_provider or providers list on the
request: they resolve to the project's own configuration of that type, or a workspace-wide
one, never another project's. A send for which no allowed provider remains fails with
no_providers.
If the first attempt returns a retryable error (rate-limited, 5xx, timeout) MessagePipe tries the next provider in the ranking. Terminal errors (auth failed, invalid recipient, blocked) short-circuit.
A project can be limited to specific providers, or made to prefer them, with provider pins. Pins apply on top of the ranking above.
Overrides
An email provider can override the project's sender, tracking and headers for the mail it
carries. Set them from the provider's page (Overrides) or with overrides on
POST /providers and PATCH /providers/{id}. Every key is optional; an empty block inherits
everything from the project.
curl -X PATCH https://app.dev.messagepipe.dev/api/providers/prv_… \
-H "Cookie: mp_session=..." \
-H "Content-Type: application/json" \
-d '{ "overrides": {
"from_email": "news@mail.example.com",
"from_name": "Example News",
"reply_to": "help@example.com",
"disable_tracking": true,
"headers": { "X-Stream": "bulk" } } }'| Key | What it does |
|---|---|
from_email, from_name, reply_to | The sender used when the send names none. Each falls back to the project's default on its own. |
disable_tracking | Turns off the provider's own open and click tracking. It cannot turn tracking on: that stays your provider account's setting. |
headers | Default custom headers (up to 20), under the same rules as headers on a send. A header of the same name on the request wins. |
Order of precedence. A from on the request or in the template wins, and when one is
given it is used whole: the provider's From name and Reply-To are not mixed in. With no
from, each sender field is the provider's override, then the project's default.
Applied per attempt. The provider that takes a send is only known at dispatch, so the overrides of the provider that actually sends are the ones used. When a send fails over, the next provider's overrides apply, and a provider with none sends as the project default.
Domain checks. A provider's From address is not checked against the project's
sender domains or a brand's
verified domains, which are checked when a send is accepted, before any provider is chosen. Use
a domain that is set up for sending (SPF and DKIM) with that provider. A marketing send is
still checked against the sender it names, or else the project's default sender, so that
sender has to exist. A send with no from and no project default sender is accepted when an
active email provider for the project has a From address of its own. If the provider that would take it has none, it is skipped and the send fails over to one that does; when no provider has a sender the send fails as all_providers_failed.
Overrides apply to email providers only; setting them on another channel is a 400. Changing
them is recorded in the audit log as provider.overrides_changed, with the previous and new
block, and they travel with a workspace export, where a From or Reply-To address follows the
domain mapping chosen on import.
Credentials at rest
Credentials are never stored in plaintext. They are encrypted the moment you save them and decrypted only at the point of dispatch.