Sign in
latestSwagger 2.02026-08-101561322.2 MB

3e4029d19684

Email Campaigns

Send email campaign

<a class="try-sandbox-link" href="https://sandbox.textmagic.com/#/Email%20Campaigns/createEmailCampaign" target="_blank">Try in sandbox</a><br>Creates a new email campaign and sends it to the specified recipients.

This endpoint allows you to create and immediately send an email marketing campaign to your contacts, groups, or direct email addresses. The campaign will be processed asynchronously, and you'll receive a campaign object with tracking information.

Request Requirements

  • Email Sender ID: Must be a valid, configured email sender from your account
  • Recipients: At least one recipient type must be specified (contacts, groups, or emails)
  • Content: Subject and HTML message content are required
  • Balance: Sufficient account balance for the estimated campaign cost

Recipient Types

You can target multiple recipient types in a single campaign:

  • Contact IDs: Send to specific contacts from your contact list
  • Group IDs: Send to all contacts within specified groups
  • Direct Emails: Send to email addresses not in your contact list

Content Guidelines

  • Subject: Maximum 998 characters, should be engaging and relevant
  • Message: HTML content supported, including images, links, and formatting
  • From Name: Optional custom sender name (max 500 characters)
  • Reply-To: Optional custom reply-to email address

Cost and Balance

The API automatically calculates campaign costs based on:

  • Total number of unique recipients across all specified groups, contacts, and emails
  • Your account's email pricing tier
  • Any additional features or premium content

If your account balance is insufficient, the request will be rejected with a low balance error.

Response Information

Successful campaigns return:

  • Campaign ID for tracking and analytics
  • Current campaign status and progress
  • Cost breakdown and recipient counts
  • Sender information and content preview
  • Statistical totals and engagement metrics

Error Scenarios

Common error conditions include:

  • Validation Errors: Invalid email addresses, missing required fields, or content that exceeds limits
  • Insufficient Balance: Account balance too low for campaign cost
  • Invalid Recipients: Non-existent contact/group IDs or invalid email formats
  • Sender Configuration: Invalid or unconfigured email sender ID
  • No Recipients: All recipient arrays are empty or invalid
post/api/v2/email-campaigns

Request body

emailSenderIdinteger required

Email sender ID from your configured senders.

subjectstring required

Email subject line.

messagestring required

HTML email content.

fromNamestring nullable

Optional custom sender name.

replyToEmailstring email nullable

Optional custom reply-to email address.

Example request

{
  "emailSenderId": 123,
  "subject": "Special Offer - 50% Off Today Only!",
  "message": "<html><body><h1>Special Offer!</h1><p>Get 50% off all products today only!</p></body></html>",
  "fromName": "John Smith",
  "replyToEmail": "support@example.com",
  "recipients": {
    "contactIds": [
      1,
      2,
      3
    ],
    "emails": [
      "user1@example.com",
      "user2@example.com"
    ],
    "groupIds": [
      10,
      20
    ]
  }
}

Response

Email campaign created successfully.

idinteger required

Unique campaign ID.

status'idle' | 'sent' | 'in_progress' | 'failed' | 'delivered' | 'rejected' | 'error' | 'scheduledError' required

Current campaign status.

emailSenderIdinteger nullable

Email sender ID used for this campaign.

startAtstring date-time required

Campaign start timestamp.

fromNamestring nullable

Sender name displayed in recipient's inbox.

fromEmailstring email required

Sender email address.

replyToEmailstring email required

Reply-to email address.

subjectstring required

Email subject line.

htmlstring required

HTML email content.

costnumber float required

Total campaign cost.

failedReason'lowBalance' | 'noRecipients' | 'noEmailSender' | 'unhandled' nullable

Reason for campaign failure if applicable.

Example response

{
  "id": 12345,
  "status": "in_progress",
  "emailSenderId": 123,
  "startAt": "2023-12-01T10:00:00Z",
  "createdBy": {
    "id": 456,
    "firstName": "John",
    "lastName": "Smith",
    "avatarUrl": "https://example.com/avatar.jpg",
    "email": "john.smith@example.com"
  },
  "fromName": "John Smith",
  "fromEmail": "noreply@example.com",
  "replyToEmail": "support@example.com",
  "subject": "Special Offer - 50% Off Today Only!",
  "html": "<html><body><h1>Special Offer!</h1><p>Get 50% off all products today only!</p></body></html>",
  "cost": 15.75,
  "totals": {
    "recipients": 1250,
    "delivered": 1180,
    "rejected": 20,
    "failed": 50,
    "opened": 590,
    "clicked": 118,
    "spamReports": 2,
    "unsubscribed": 5
  },
  "outboundEmail": {
    "id": 78901,
    "sendTime": "2023-12-01T10:05:00Z",
    "fromName": "John Smith",
    "fromEmail": "noreply@example.com",
    "replyToEmail": "support@example.com",
    "recipientFullName": "Jane Doe",
    "recipientEmail": "jane.doe@example.com",
    "emailSubject": "Special Offer - 50% Off Today Only!",
    "emailContent": "<html><body><h1>Special Offer!</h1><p>Get 50% off all products today only!</p></body></html>",
    "source": "emailCampaign",
    "status": "delivered",
    "cost": 0.012,
    "statusReason": "Successfully delivered",
    "contactId": 123,
    "initiatorId": 456
  },
  "failedReason": "lowBalance"
}