Skip to main content

​
Send vs Send Async

There are two ways to send an email: synchronously and asynchronously. When you send an email synchronously, your application waits for the API to process the request and return a response. For a single email, this is usually pretty quick. But for larger sends, the processing time can take much longer. When you send an email asynchronously, your application makes a request and immediately receives a response. In the background, the API processes the request. Your application does not wait. In order to track the status of the send, you will receive webhooks for all delivery status updates (dropped, processed, delivered, hard-bounced, etc.). These webhooks are identical to the webhooks you receive for synchronous sends.

​
When to use Send vs Send Async

Synchronous sending should only be used when the user needs feedback on the status of the send before proceeding, and the number of emails being sent is small. Our evaluation process can take several seconds per message. Asynchronous sending should be used for most requests. It is important to have webhooks set up to receive delivery status updates. You can view webhook events on the webhooks page. For more information on webhooks, see the webhooks documentation.

​
Examples

Send synchronously: 
#!/usr/bin/env bash
# Send an email synchronously

  set -u
  : "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
  : "${FROM_EMAIL:?Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)}"
  : "${TO_EMAIL:?Set TO_EMAIL}"

curl -X POST https://api.mailchannels.net/tx/v1/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
  -d @- <<JSON
{
  "personalizations": [
    { "to": [{ "email": "$TO_EMAIL", "name": "Recipient" }] }
  ],
  "from": {
    "email": "$FROM_EMAIL",
    "name": "Your Name"
  },
  "subject": "Hello from MailChannels (sync)",
  "content": [
    {
      "type": "text/plain",
      "value": "This message was sent with POST /tx/v1/send. The caller waited for the response."
    }
  ]
}
JSON
Send asynchronously: 
#!/usr/bin/env bash
# Send an email asynchronously.

  set -u
  : "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
  : "${FROM_EMAIL:?Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)}"
  : "${TO_EMAIL:?Set TO_EMAIL}"

curl -X POST https://api.mailchannels.net/tx/v1/send-async \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
  -d @- <<JSON
{
  "personalizations": [
    { "to": [{ "email": "$TO_EMAIL", "name": "Recipient" }] }
  ],
  "from": {
    "email": "$FROM_EMAIL",
    "name": "Your Name"
  },
  "subject": "Hello from MailChannels (async)",
  "content": [
    {
      "type": "text/plain",
      "value": "This message was sent with POST /tx/v1/send-async. Delivery status will arrive via webhook."
    }
  ]
}
JSON