Skip to main content

Sending Email with Attachments

Attaching a file to an outbound email is a two-step flow:

  1. Upload the file to get an attachment ID.
  2. Send the email referencing that ID.

The important detail is which send endpoint you use in step 2. Three endpoints accept attachments correctly:

  • POST /api/v1/messages — the unified send endpoint (use its attachments array).
  • POST /api/v1/email-integrations/email-messages/{id}/reply — replying to an inbound email (use its attachment_ids array).
  • POST /api/v1/email-integrations/conversations/{id}/compose-email — starting a new outbound email in a conversation (use its attachment_ids array).

All three accept the attachment IDs returned by the upload endpoints below.

Step 1 — Upload the file​

Upload a local file:

curl -X POST "https://api.sendseven.com/api/v1/attachments/upload" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -F "file=@/path/to/invoice.pdf"

...or attach a file already hosted at a URL:

curl -X POST "https://api.sendseven.com/api/v1/attachments/from-url" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://cdn.acme.com/files/invoice.pdf", "filename": "invoice.pdf" }'

Both return an attachment record. Use its id:

{
  "id": "9b3f1a8e-7c2d-4e5b-9f01-12a3b4c5d6e7",
  "filename": "invoice.pdf",
  "content_type": "application/pdf",
  "file_size": 84210
}

See Upload an attachment and Attach from URL for full details.

Step 2 — Send the email with the attachment​

Using POST /messages (recommended)​

Reference the uploaded IDs in the attachments array. Email is never fanned out — one email carries all the files as MIME parts.

curl -X POST "https://api.sendseven.com/api/v1/messages" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_email_99",
    "subject": "Your invoice",
    "text": "Please find your invoice attached.",
    "message_type": "document",
    "attachments": ["9b3f1a8e-7c2d-4e5b-9f01-12a3b4c5d6e7"]
  }'

Remember that email requires a subject — include subject, or send into a conversation that already has one. See Sending email.

Replying to an inbound email with an attachment​

When replying to a customer's email, use the reply endpoint's attachment_ids array with the same uploaded IDs:

curl -X POST "https://api.sendseven.com/api/v1/email-integrations/email-messages/em_12345/reply" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "text_body": "Here is the document you requested.",
    "attachment_ids": ["9b3f1a8e-7c2d-4e5b-9f01-12a3b4c5d6e7"]
  }'

Composing a new email with an attachment​

To start a brand-new outbound email (rather than reply to an inbound one), use the compose endpoint's attachment_ids array with the same uploaded IDs:

curl -X POST "https://api.sendseven.com/api/v1/email-integrations/conversations/conv_email_99/compose-email" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Your invoice",
    "text_body": "Please find your invoice attached.",
    "attachment_ids": ["9b3f1a8e-7c2d-4e5b-9f01-12a3b4c5d6e7"]
  }'

The attachment_ids here are the same generic attachment IDs returned by /attachments/upload and /attachments/from-url — the identical IDs POST /messages and the reply endpoint accept. An ID that does not resolve to an attachment your workspace owns is rejected with 404 Attachment {id} not found — the email is not sent with the file silently missing.

Inline images (embedded)​

An inline image is displayed inside the email body (for example a logo in a signature, or a screenshot in the middle of a sentence) rather than listed as a separate downloadable file. This works on the endpoints that accept an HTML body — the reply and compose-email endpoints — via their html_body field.

The flow has three parts:

  1. Upload the image to the inline-image endpoint, which returns a content_id:

    curl -X POST "https://api.sendseven.com/api/v1/email-integrations/inline-images/upload" \
      -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
      -F "file=@/path/to/logo.png"
    {
      "attachment_id": "9b3f1a8e-7c2d-4e5b-9f01-12a3b4c5d6e7",
      "content_id": "9b3f1a8e-7c2d-4e5b-9f01-12a3b4c5d6e7@inline",
      "url": "https://.../logo.png"
    }

  2. Reference the image in your html_body with <img src="cid:{content_id}">, using the exact content_id string the upload returned (do not construct your own).

  3. Include the attachment_id in the same request's attachment_ids array.

curl -X POST "https://api.sendseven.com/api/v1/email-integrations/conversations/conv_email_99/compose-email" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Welcome to Acme",
    "html_body": "<p>Thanks for joining!</p><img src=\"cid:9b3f1a8e-7c2d-4e5b-9f01-12a3b4c5d6e7@inline\">",
    "attachment_ids": ["9b3f1a8e-7c2d-4e5b-9f01-12a3b4c5d6e7"]
  }'

Any attachment whose content_id appears as a cid: reference in html_body is sent as an embedded inline part (it renders where the <img> sits) and is not also listed as a separate file attachment. Attachments whose content_id is not referenced in the body stay ordinary downloadable files, so you can mix inline images and regular attachments in one email. Inline images count toward the same 20 MB total.

note

POST /messages sends a plain-text email body and does not carry an HTML body, so inline (cid:) embedding applies to the reply and compose-email endpoints. Attachments referenced through POST /messages are always delivered as regular file attachments.

Limits​

LimitValue
Maximum total attachment size per email20 MB (raw, before encoding)
Files per emailMultiple — all attached to the single email
Size ceiling

Email providers cap the encoded message size, and base64 encoding inflates a file by roughly a third. SendSeven enforces a 20 MB raw total across all attachments on one email. A larger file is rejected loudly rather than sending an email with the file silently missing. (The general upload limit is higher, so it is possible to upload a file that is too large to email.)

Next steps​