Send an email
Send one email to one person from your connected Gmail.
/api/v1/emailsemail:writeSends one email to one person, exactly like the Email tab in Pedibee:
- It goes out from the Gmail the key is set to send from (chosen when the key is created). If that Gmail is disconnected, sends are refused until you pick another in Settings → API keys.
- The recipient becomes a contact if they aren't one already, and the email is recorded on their history.
- Opens and clicks are tracked when your workspace has an active tracking domain. Each can be turned off per email.
- Addresses on your do-not-email list are always refused. Contacts marked replied, bounced, unsubscribed, converted or dead are refused unless you send
force: true.
Body
Send a JSON object.
Prop
Type
Every email is sent with a plain-text version made from its HTML, so it reads well in any mail app.
Example request
curl -X POST "https://api.pedibee.com/api/v1/emails" \
-H "Authorization: Bearer $PEDIBEE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "jane@northwind.io",
"subject": "Quick question about Northwind'\''s onboarding",
"html": "<p>Hi Jane,</p><p>Saw your team is growing — <a href=\"https://pedibee.com\">here'\''s how we help</a>.</p>",
"signatureId": "default"
}'Response
What was sent. id is Gmail's id for the message; tracked says whether tracking was added.
{
"id": "18c2f4a9b7e3d001",
"to": "jane@northwind.io",
"cc": [],
"from": "Alex Morgan <alex@yourcompany.com>",
"subject": "Quick question about Northwind's onboarding",
"sentAt": "2026-10-05T09:30:00.000Z",
"tracked": true,
"contactId": "66f1c2a9e4b0a1b2c3d4e5f6",
"contactCreated": false
}Sending later
Add sendAt and the email is kept until then instead of sent now; the answer is 201 with scheduled: true and the scheduled email (id, status: "SCHEDULED", sendAt). It goes out within about a minute of its time, through exactly the same send — so the do-not-email list, the contact's stage, the signature, tracking and the Gmail's daily limit are all checked when it goes out. If the Gmail has used up its day, it waits and goes out as soon as there's room. See Scheduled emails to list, change or cancel them.
Limits
Up to 20 emails a minute and 300 a day per key, and the same across all keys for one Gmail. Every email also counts towards the Gmail's daily sending limit, shared with campaigns, sequences and the Email tab. Over a limit you get 429 with Retry-After.
Sending to many people?
This endpoint is for one-off emails, like a reply to a sign-up. To email many people, add them to a list and send a campaign or sequence from the dashboard: it paces sending, skips people who shouldn't be emailed and adds an unsubscribe link.
Errors
Every error is { "error": "…" } with a message you can show. See Errors and limits.
| Status | When |
|---|---|
400 | to or subject is missing, both or neither of html and text were sent, an address is invalid, the contact is marked replied, bounced, unsubscribed, converted or dead (without force), the address is on the do-not-email list, or the key's Gmail is no longer connected. |
403 | The key doesn't have email:write, or its creator can no longer send. |
404 | signatureId isn't in your workspace. |
429 | The Gmail has reached its daily sending limit, shared with campaigns and sequences. |
502 | Gmail refused or failed to send. The message says why. |
401 | The API key is missing, invalid, revoked or expired. |
429 | Too many requests. Wait for the seconds in Retry-After. |