Basic Send

Send a single transactional email instantly using the Sendliberty REST API.

To send an email, make a secure HTTP POST request to the /api/send endpoint. If you have connected multiple Gmail accounts, you can specify which one to use by passing the from field in your request body. If omitted, Sendliberty automatically defaults to your first connected Gmail account.

Example Request

Authentication Headers
You can authenticate your requests with Sendliberty in two ways:
  • Authorization Header: Send your API key as a Bearer token: Authorization: Bearer YOUR_API_KEY
  • Custom x-api-key Header: If your HTTP client or environment makes Bearer auth difficult, pass it directly: x-api-key: YOUR_API_KEY
Request Body Parameters
  • from (string, required): The connected Gmail email address you want to send this email from. You can optionally include a custom display name by using the format "Your Brand Name" <yourproduct@gmail.com>.
    Pro Tip
    Look Professional with Display Names
    By default, if you just send your email address (e.g. yourproduct@gmail.com or in my case, samueltuoyo9082@gmail.com), that is exactly what your recipients will see in their inbox. This can look unprofessional.
    Instead, we highly recommend adding a Display Name. Just format your address like this:
    Comparison between using a display name and not using one
    Top: Format using "Sendliberty" <samueltuoyo9082@gmail.com>
    Bottom: Format using just samueltuoyo9082@gmail.com
  • to (string or array of strings): The recipient's email address (or array of addresses).
  • subject (string): The subject line of the email.
  • html (string): The HTML body content of the email.
  • text (string, optional): The plain text fallback body.
  • replyTo (string, optional): Setup a reply-to email address.
  • cc (string or array of strings, optional): carbon copy recipient(s).
  • bcc (string or array of strings, optional): blind carbon copy recipient(s).
  • attachments (array of objects, optional): An array of attachments to include:
    • filename (string, required): The name of the file (e.g. invoice.pdf).
    • content (string, required): The base64-encoded file content.
    • type (string, optional): The MIME content type (e.g. application/pdf).
Need details on rate limits or request body size caps? Check out the Limits & Quotas documentation page.
Sending concurrently? Requests using the same personal Gmail account are limited to one accepted send per second; Google Workspace accounts are limited to two per second. Sendliberty waits for up to 3 seconds for a slot, then records a failed log and returns 429 with a Retry-After header. Serialize sends per Gmail account and retry only after the indicated delay, or use /api/batch for a recipient list.
Best Practices for Deliverability
When sending emails from a personal @gmail.com account (as opposed to a verified Google Workspace custom domain), Google's spam filters can be highly aggressive. A successful API response means Gmail accepted the message; it cannot guarantee that Gmail or the recipient's provider will place it in the primary inbox. To improve your chances of inbox placement, we strongly recommend the following:
  • Send plain text or light HTML: Avoid heavy layouts, large images, and giant colorful buttons. The more your email looks like a genuine 1-on-1 human email, the better.
  • Minimize links: Try to include zero or at most one link in your first cold email to a new recipient.
  • Avoid spam trigger words: Do not use highly commercial language like "Action Required", "Free Trial", "Buy Now", or "Upgrade".
  • Only email expecting recipients: Sendliberty automatically throttles your sending speed to keep you under Google's radar, but if a high percentage of recipients manually click "Report Spam", Google will permanently penalize your connected account.
Example: Avoiding Spam Triggers
High Spam Risk
Subject:Action Required: Your Account is Disconnected!
From:hello@company.com
URGENT: We detected an error.
Click the button below to fix it immediately or lose access.
Inbox Friendly
Subject:Quick update regarding your connection
From:"Alex at Company" <hello@company.com>
Hi John,
We recently rolled out an update that might have disconnected your account.
You can easily restore it by visiting your dashboard.
Thanks,
Alex
Ideal Use Cases
Sendliberty is intentionally designed for high-deliverability 1-on-1 communication. It is not designed for heavy, image-packed marketing blasts.
Great for Sendliberty
  • Password resets & Magic links
  • Payment receipts & Invoices
  • System alerts & Downtime Notifications
  • Welcome emails from the founder
  • Personalized cold outreach
  • New feature announcements to active users
  • Trial expiration warnings
  • Weekly usage summary reports
Bad for Sendliberty
  • Weekly marketing newsletters
  • Image-heavy promotional blasts
  • E-commerce product catalogs
  • Discount code mass mailings
PreviousAPI KeysNextBatch Send