Create & Send emails

Learn how to send emails using Unipile API.

Email deliverability

Emails sent through Unipile use the connected provider's sending infrastructure. Your existing domain authentication still applies. For custom domains, verify that SPF, DKIM and DMARC are configured correctly with your email administrator; connecting an account to Unipile does not configure these records.

However, if your system involves outreach or automatic sending at higher volumes, it's advisable to verify the proper configuration of these parameters to ensure optimal deliverability at scale.

When sending to personal Gmail accounts, Google requires reported spam rates to remain below 0.3%. Senders exceeding 5,000 messages per day must meet additional requirements, including SPF, DKIM and DMARC authentication. Other receiving providers have their own requirements.

📘

Sending emails for different purposes

You can send emails for different purposes from connected accounts, such as notifications, marketing or outreach. For large marketing campaigns, prefer a dedicated email sending service, built for high volumes with IP reputation management, bounce handling and unsubscribe management.


Provider limitations

Google

Gmail and Google Workspace accounts have different sending capacities: Gmail allows up to 500 emails per day, while paid Workspace accounts allow up to 2,000. Workspace trial accounts have lower limits, typically 500 messages per day. Workspace daily limits apply over a rolling 24-hour period. In practice, though, it’s best to stay well below these official caps to avoid being flagged. For Gmail, sending 50–100 emails per day is recommended (up to 150 if your reputation is strong), while Workspace is safer around 100–150 per day (up to 300 with good engagement). For new accounts, always start slowly — around 20–50 emails per day — and increase gradually as your reputation builds.

Beyond volume, Gmail also enforces API quotas that apply across all actions. If you send too many requests at once, you’ll quickly run into 429 Too Many Requests errors, so you need to spread calls over time. See the Gmail API quota reference for details.

If you need more flexibility, Google Workspace lets you create multiple domains and link them as aliases to your main account. With Unipile’s API you can list these aliases and use an authorized address in the from field. Messages sent through aliases count toward the same account's sending limits. More details are available in Google’s documentation.


Outlook

For Outlook.com accounts with a Microsoft 365 subscription, sending limits are higher but still enforced. You can send email to up to 5,000 recipients per day, with a maximum of 500 recipients per single message. Within that total, no more than 1,000 can be “non-relationship recipients” — people you haven’t emailed before. These numbers may be lower for non-subscribers, and limits can also adjust depending on your account’s usage history. If you send mail through third-party connected accounts, the provider’s own limits will apply.

Microsoft 365 business accounts using Exchange Online have different limits: up to 10,000 recipients per day, a configurable per-message limit of up to 1,000 recipients, and 30 messages per minute. Mailbox settings, tenant-wide external-recipient limits and other provider restrictions can further reduce these limits.

Beyond these official caps, it’s wise to follow the same best practices described in the Gmail section: keep your daily sending volumes conservative, grow gradually, and prioritize quality engagement to protect your deliverability.


Other providers

The limitations may vary depending on your email provider. Please refer to your users provider's documentation or inquire with them directly for specific details.

Apart from official recommendations, we advise respecting the "Recommended Sending Limits" in Gmail part


Build an email

📘

Required permissions

The connected account must have the permissions required by the operations you use. Outlook sending requires both Mail.Send and Mail.ReadWrite. Gmail replies also require permission to read the original message. IMAP accounts need working SMTP credentials.

See Methods & Scope for the complete requirements. Reconnect an existing account when requesting different OAuth permissions.


For the following examples we'll use this built email:

const email = {
  to: [
    {
      display_name: 'John Doe',
      email: '[email protected]',
    },
  ],
  cc: [
    {
      display_name: 'Jane Doe',
      email: '[email protected]',
    },
  ],
  subject: 'Hello',
  plain_text: 'Hello, world!',
  html: '<p>Hello, world!</p>',
}
email = {
    "to": [
        {
            "display_name": "John Doe",
            "email": "[email protected]",
        }
    ],
    "cc": [
        {
            "display_name": "Jane Doe",
            "email": "[email protected]",
        }
    ],
    "subject": "Hello",
    "plain_text": "Hello, world!",
    "html": "<p>Hello, world!</p>",
}

We recommend to set a plain text even if your email contains HTML as it is used by clients to display a snippet of the email in Inboxes.

Choose a sender

Use List email senders to retrieve the sender addresses exposed by a Google or Outlook account:

curl --request GET \
     --url https://api.unipile.com/v2/account_id/email-senders \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json'

Use the selected address in from when sending an email or creating a draft:

{
  "from": {
    "email": "[email protected]",
    "display_name": "Support"
  }
}

For Gmail, check verification_status: an address marked pending is not ready for sending. Outlook addresses are marked unknown; sending from an alias depends on the mailbox's permissions and tenant configuration.

Additional Outlook addresses are exposed for Microsoft 365 / Exchange accounts. Personal Microsoft accounts return the primary address only. Sender discovery is not available for IMAP.

For IMAP, use an address allowed by the SMTP provider. Provide from explicitly if the SMTP username is not an email address. The optional display_name is supported when composing emails and drafts.

Gmail sender information can also include an HTML signature. Append it to your email's html yourself; signatures are not added automatically. A signature may be absent, including for some Gmail aliases. Outlook signatures are not returned.


Set reply behavior

Use reply_to to set the standard Reply-To header. It accepts a list of attendees and controls the addresses that
receive replies instead of the address in from:

{
  "reply_to": [
    {
      "display_name": "Support",
      "email": "[email protected]"
    }
  ]
}

To reply inside an existing email conversation with Send an Email, use reply_to_provider_id. For Gmail, Outlook and IMAP, provide the original Email object's id:

{
  "reply_to_provider_id": "original_email_id"
}

The older reply_to_message_id field remains accepted for direct sending but is deprecated. For Gmail and Outlook it takes the provider message ID; for IMAP it takes the RFC822 Message-ID header. When both fields are provided, reply_to_provider_id takes precedence.

For IMAP, sending with reply_to_provider_id also attempts to mark the original email as answered after SMTP succeeds. A failure to update that flag does not change the successful send result. Legacy replies using reply_to_message_id do not mark the original email as answered.

When creating a reply draft with Create a Draft, continue to use reply_to_message_id:

ProviderValue
GmailThe original Email object's id
OutlookThe original Email object's id
IMAPThe original email's RFC822 Message-ID header, exposed as message_id
{
  "reply_to_message_id": "original_message_identifier"
}

Outlook supports native reply drafts. Omitting subject and content preserves Outlook's native subject and quoted body; providing content replaces that body. When updating an Outlook reply draft, omit reply_to_message_id: its conversation is preserved, but its parent cannot be changed.

Provide the intended to and cc recipients explicitly when implementing reply-all. For Gmail replies, retain the original subject so the message can remain in the same thread.

The reply_to address header is available for direct sending and drafts. A Reply-To header supplied through custom_headers takes precedence over reply_to on direct sends.


Send from a draft

A draft is a saved email that is not ready to be sent.

To create a new draft, use the Create a Draft method. This will create a new email in the Drafts mailbox.

const { data } = await emailsApi.createDraft({
  path: {
    account_id: "acc_123456789",
  },
  body: email,
});

const draft_id = data.id;
draft = emails_api.create_draft("acc_123456789", email)
draft_id = draft.id
curl --request POST \
     --url https://api.unipile.com/v2/account_id/drafts \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "html": "<p>Hello, world!</p>",
  "plain_text": "Hello, world!",
  "subject": "Hello",
  "to": [
    {
      "email": "[email protected]",
      "display_name": "John Doe"
    }
  ],
  "cc": [
    {
      "display_name": "Jane Doe",
      "email": "[email protected]"
    }
  ]
}
'

Then, you can edit the draft using Update a Draft.

When updating a draft, a supplied attachments array replaces the existing attachments. Omit the field to retain them, or provide an empty array to remove them.

If you update the draft, keep the id returned by Update a Draft and use that ID when sending. In particular, updating an IMAP draft can change its ID.

Once the Draft is ready to be sent, use the Send a Draft method and provide the ID of the Draft.

In this exemple, we use the draft_id from the response of Create a Draft, but you can get IDs by using List all Drafts.

await emailsApi.sendDraft({
  path: {
    account_id: "acc_123456789",
    draft_id,
  },
});
emails_api.send_draft("acc_123456789", draft_id)
curl --request POST \
     --url https://api.unipile.com/v2/account_id/drafts/draft_id/send \
     --header 'accept: application/json'

Send directly

To send an email from the linked account, use Send an Email method and provide the email content.

await emailsApi.sendEmail({
  path: {
    account_id: "acc_123456789",
  },
  body: email,
});
emails_api.send_email("acc_123456789", email)
curl --request POST \
     --url https://api.unipile.com/v2/account_id/emails/send \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "to": [
    {
      "display_name": "John Doe",
      "email": "[email protected]"
    }
  ],
  "subject": "Hello",
  "plain_text": "Hello, world!",
  "html": "<p>Hello, world!</p>"
}
'

Set custom headers

Send an Email accepts a custom_headers array:

{
  "custom_headers": [
    {
      "name": "X-Reference-ID",
      "value": "reference-123"
    }
  ]
}

Custom headers override headers with the same name, ignoring case, including headers populated from from, to, cc, bcc, subject or reply_to.

Outlook replies support Reply-To but reject other custom headers when replying through reply_to_provider_id or reply_to_message_id.

The custom_headers field is not available when creating or updating drafts.


Send attachments

To send attachments, include files in the attachments array.

For JSON requests, the content of the file must be encoded to base64. The entire JSON body is limited to 1 MiB, including the email content and base64-encoded attachments. Use multipart for larger uploads.

const file = await readFile('document.pdf');

await emailsApi.sendEmail({
  path: {
    account_id: "acc_123456789",
  },
  body: {
    ...email,
    attachments: [
      {
        content: file.toString('base64'),
        content_type: 'application/pdf',
        filename: 'document.pdf',
      },
    ],
  },
});
import base64

with open("document.pdf", "rb") as f:
    content = base64.b64encode(f.read()).decode("utf-8")

emails_api.send_email(
    "acc_123456789",
    {
        **email,
        "attachments": [
            {
                "content": content,
                "content_type": "application/pdf",
                "filename": "document.pdf",
            }
        ],
    },
)
curl --request POST \
     --url https://api.unipile.com/v2/account_id/emails/send \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "to": [
    {
      "display_name": "John Doe",
      "email": "[email protected]"
    }
  ],
  "subject": "PDF",
  "attachments": [
    {
      "content": "$(base64 -b 0 -i document.pdf)",
      "content_type": "application/pdf",
      "filename": "document.pdf"
    }
  ]
}
'

Send files with multipart

Use multipart to upload files directly without base64 encoding:

curl --request POST \
     --url https://api.unipile.com/v2/account_id/emails/send \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --form 'to[0][email][email protected]' \
     --form 'to[0][display_name]=John Doe' \
     --form 'subject=PDF' \
     --form 'attachments[0][email protected];type=application/pdf'

Let your HTTP client set the multipart Content-Type and boundary.

Multipart is supported by Send an Email, Create a Draft and Update a Draft.

Embed inline images

Set an attachment's content_id and reference it from the HTML using cid::

const image = await readFile('image.png');

await emailsApi.sendEmail({
  ...request_options,
  path: {
    account_id: "acc_123456789",
  },
  body: {
    ...email,
    html: '<p>Hello, world!</p><img src="cid:my-image" alt="Attached image">',
    attachments: [
      {
        content: image.toString('base64'),
        content_type: 'image/png',
        filename: 'image.png',
        content_id: 'my-image',
      },
    ],
  },
});

Provide content_id without surrounding angle brackets. The value after cid: must match it. Inline attachments are also supported when creating or updating drafts.

📘

Good to know

Be aware of size and format limitations when sending files. We recommend keeping the total email size under 25 MB, including its content, attachments and encoding overhead. Your provider may impose lower limits.

For Outlook drafts and native replies, each attachment must be smaller than 3 MB. Multipart uploads do not bypass provider limits.

Track clicks & opens

To enable tracking, provide a non-empty html field and include tracking_options:

{
  "tracking_options": {
    "opens": true,
    "clicks": true,
    "label": "email-reference-123"
  }
}

Configure a webhook subscribed to tracking.open, tracking.click, or both before composing the tracked email. Tracking is inserted into the HTML only when a matching webhook exists for the account.

These options are also available when creating or updating a draft. See Track clicks & opens for custom tracking domains, link exclusions and event payloads.

Handle sending failures

Temporary SMTP connection failures can return 503 provider/service_unavailable. Provider rejections can return 422 provider/unprocessable_entity; inspect the error details before changing the email or retrying.



Did this page help you?