DOCS

New!

/

10 minute read

August 3, 2019

Transmissions

Use the /transmissions endpoint to send payment information to a recipient securely by email or fax. The transmission includes details for a single-use virtual card, along with optional metadata that is relevant to the payment. For example, you might need to forward booking details to a hotel to fulfill a travel service you provide.

For each transmission, you must specify a template that defines the layout and formatting of the content included. The Marqeta platform provides a basic template (named "default") that displays the virtual card alongside a table of metadata.

  • Fax transmissions include the payment card data and metadata printed on the page.

  • Email transmissions include a secure link to the payment card information and metadata.

By default, the link expires 48 hours after creation and can only be accessed three times before becoming non-functional.

Note
If you are interested in using this feature, contact your Marqeta representative for more information.

Create and send transmission

Action: POST
Endpoint: /transmissions

A transmission is an email or fax sent to a recipient and includes a single-use virtual payment card with optional message and metadata. The transmission is formatted based on the specified template.

When you create a new transmission, the Marqeta platform automatically sends it to the specified recipient—you do not need to make a separate API call. The Marqeta platform response includes the transmission_outbounds object, which you can use to track the state of each send attempt.

The following image shows a sample fax transmission:

null

Is this helpful?

The following image shows a sample email transmission:

null

Is this helpful?

Body field details

Fields Description

token

string, optional

The unique identifier of the transmission.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls. This value cannot be updated.

Allowable Values:

36 char max

transmission_method

string, required

The channel by which a transmission is sent.

Allowable Values:

EMAIL, FAX

card_token

string, required

The token that identifies the single-use virtual card to include in the transmission.

Allowable Values:

An existing single-use virtual card token.

Send a GET request to /cards/user/{token} to retrieve card tokens for a particular user.

fax_recipient

string, optional

The fax number of the intended recipient.

Required if transmission_method is FAX.

Allowable Values:

Format your fax number as +(country code)(area code)(fax number) with no spaces or hyphens. For example, +1231231234.

email_recipient

string, optional

The email address of the intended recipient.

Required if transmission_method is EMAIL.

Allowable Values:

255 char max

from

string, optional

If transmission_method is FAX, the fax number of the transmission sender to be printed on the transmission.

If transmission_method is EMAIL, the email address that populates the 'from' field of the email message. If an email address without a "marqeta.com" domain is provided, the email address that populates the 'reply-to' field of the email message.

Note
If no email address is provided, or if the email address provided does not use the "marqeta.com" domain, the "from" field of the email message is populated with "no-reply@marqeta\.com".

Allowable Values:

If transmission_method is FAX, format your fax number as +(country code)(area code)(fax number) with no spaces or hyphens. For example, +1231231234.

recipient

string, required

A descriptive name of the fax or email recipient.

Allowable Values:

255 char max

subject

string, required

A high-level subject line description of the transmission contents.

Allowable Values:

255 char max

message

string, optional

The message body of the transmission.

Allowable Values:

1024 char max

logo_location

string, optional

The URL of the logo that appears in the fax template or email message.

Allowable Values:

A valid URL for an image no larger than 250 x 250.

Supported image formats include GIF, PNG, and JPG.

metadata

object, optional

An object containing custom metadata.

Allowable Values:

template_token

string, required

The token that identifies the template to use with the transmission; the template defines the layout and formatting of the transmission.

Allowable Values:

A template token, or "default".

The metadata object

Fields Description

_custom_name_01_ + _custom_name_02_ +

_..._ +

_custom_name_20_ +

string, optional

Custom data transmitted with the card data. You can define the names and values of up to 20 fields, for example:

"metadata": {
  "my_name_1": "my_value_1",
  "my_name_2": "my_value_2"
}

Allowable Values:

  • Up to 20 name-value pairs

  • 255 char max per name

  • 255 char max per value

The transmission_outbounds object (response only)

Name Type Description Allowable Values

state

string

The status of the transmission outbound.

  • QUEUED – The transmission is ready and will be sent soon.

  • SENT – The transmission was sent to the recipient.

  • FAILED – The transmission was not sent; you must resend the transmission.

Note
Send a GET request to /transmissions/{token} to retrieve the transmission record and review its state.

QUEUED, SENT, FAILED

link_expiration_time

string

The date and time when the link sent in the transmission email expires.

yyyy-MM-dd HH:mm:ss

Sample request body

{
  "transmission_method": "EMAIL",
  "card_token": "e02cf1fa-75a5-48ab",
  "email_recipient": "reservations@hotel.com",
  "from": "sender@business.com",
  "recipient": "John S",
  "subject": "Hotel reservation",
  "logo_location": "https://assets.marqeta.com/assets/marqeta_mark-64f44306840a5af3aad1aa4b4bd54ddd7e85435e578e4a90b5c16205f45a1e63.png",
  "template_token": "zabz8b83-afdb-4afd-ac4e-49bc7cde6ccc",
  "metadata": {
    "hotel_name": "Hilton",
    "total_days": "3"
  }
}

Is this helpful?

Sample response body

{
    "token": "4441064f-0f8e-4eed-aad8-d7d756b5ecc7",
    "transmission_method": "EMAIL",
    "card_token": "e02cf1fa-75a5-48ab",
    "email_recipient": "reservations@hotel.com",
    "from": "sender@business.com",
    "recipient": "John S",
    "subject": "Hotel reservation",
    "logo_location": "https://assets.marqeta.com/assets/marqeta_mark-64f44306840a5af3aad1aa4b4bd54ddd7e85435e578e4a90b5c16205f45a1e63.png",
    "template_token": "zabz8b83-afdb-4afd-ac4e-49bc7cde6ccc",
    "metadata": {
        "hotel_name": "Hilton",
        "total_days": "3"
    },
    "created_time": "2018-02-05 18:59:57",
    "last_modified_time": "2018-02-05 18:59:58",
    "transmission_outbounds": [
        {
            "state": "SENT",
            "link_expiration_time": "2018-02-05 19:59:57",
            "created_time": "2018-02-05 18:59:57",
            "last_modified_time": "2018-02-05 18:59:57"
        }
    ],
    "transmission_attempt_count": 1
}

Is this helpful?

Resend transmission

Action: PUT
Endpoint: /transmissions/{token}/resend

Resend a specific transmission. You can resend transmissions up to three times.

URL path parameters

Fields Description

token

string, required

The identifier of the transmission.

Allowable Values:

An existing transmission token.

Send a GET request to /transmissions to retrieve transmission tokens.

Sample response body

{
  "token": "9f2a1457-7471-4efd-a967-bc58194db8a4",
  "transmission_method": "EMAIL",
  "card_token": "e02cf1fa-75a5-48ab",
  "email_recipient": "reservations@hotel.com",
  "from": "sender@business.com",
  "recipient": "John S",
  "subject": "Hotel reservation",
  "logo_location": "https://assets.marqeta.com/assets/marqeta_mark-64f44306840a5af3aad1aa4b4bd54ddd7e85435e578e4a90b5c16205f45a1e63.png",
  "template_token": "65452623-f049-49ea-8fcc-61ff039f4b50",
  "metadata": {
    "hotel_name": "Hilton",
    "total_days": "3"
  },
  "created_time": "2018-02-05 19:43:49",
  "last_modified_time": "2018-02-05 20:50:45",
  "transmission_outbounds": [
    {
      "state": "SENT",
      "link_expiration_time": "2018-02-05 20:43:54",
      "created_time": "2018-02-05 19:43:54",
      "last_modified_time": "2018-02-05 19:43:54"
    },
    {
      "state": "SENT",
      "link_expiration_time": "2018-02-05 21:50:42",
      "created_time": "2018-02-05 20:50:42",
      "last_modified_time": "2018-02-05 20:50:42"
    }
  ],
  "transmission_attempt_count": 2
}

Is this helpful?

List transmissions

Action: GET
Endpoint: /transmissions

List existing transmissions. This endpoint supports pagination and field filtering.

Query parameters

Fields Description

transmission_method

string, optional

Returns transmissions sent by the specified method.

Allowable Values:

EMAIL, FAX

card_token

string, optional

Returns transmissions associated with the specified card.

Allowable Values:

An existing single-use virtual card token.

Send a GET request to /cards/user/{token} to retrieve card tokens for a particular user.

from

string, optional

Returns transmissions from the given email address.

Allowable Values:

255 char max

recipient

string, optional

Returns transmissions associated with the specified recipient.

Allowable Values:

255 char max

template_token

string, optional

Returns templates using the specified template token.

Allowable Values:

A template token, or "default".

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": true,
  "data": [
    {
      "token": "40cz0068-6c02-4za9-b4cd-6145cfffa36z",
      "transmission_method": "EMAIL",
      "card_token": "e02cf1fa-75a5-48ab",
      "email_recipient": "reservations@hotel.com",
      "from": "sender@business.com",
      "recipient": "John S",
      "subject": "Your reservation",
      "template_token": "6abf8b83-afdb-4afd-ac4e-49bc7cde6ccc",
      "metadata": {
        "hotel_name": "Hilton",
        "total_days": "3"
      },
      "created_time": "2018-01-25 10:08:04",
      "last_modified_time": "2018-01-25 10:08:09",
      "transmission_outbounds": [
        {
          "state": "FAILED",
          "link_expiration_time": "2018-01-25 11:08:07",
          "created_time": "2018-01-25 10:08:07",
          "last_modified_time": "2018-01-25 10:08:07"
        }
      ],
      "transmission_attempt_count": 1
    },
    {
      "token": "4825e50c-ec16-420f-a48d-dea80e163c70",
      "transmission_method": "EMAIL",
      "card_token": "e02cf1fa-75a5-48ab",
      "email_recipient": "reservations@hotel.com",
      "from": "sender@business.com",
      "recipient": "John S",
      "subject": "Hotel reservation",
      "template_token": "5c66f6ac-5c31-4fa0-b183-13e9097cb4de",
      "metadata": {
        "hotel_name": "Hilton",
        "total_days": "3"
      },
      "created_time": "2018-02-05 18:59:57",
      "last_modified_time": "2018-02-05 18:59:58",
      "transmission_outbounds": [
        {
          "state": "SENT",
          "link_expiration_time": "2018-02-05 20:43:54",
          "created_time": "2018-02-05 19:43:54",
          "last_modified_time": "2018-02-05 19:43:54"
        }
      ],
      "transmission_attempt_count": 1
    }
  ]
}

Is this helpful?

Retrieve transmission

Action: GET
Endpoint: /transmissions/{token}

Retrieve a specific transmission.

URL path parameters

Fields Description

token

string, required

The identifier of the transmission.

Allowable Values:

An existing transmission token.

Sample response body

{
  "token": "9f2a1457-7471-4efd-a967-bc58194db8a4",
  "transmission_method": "EMAIL",
  "card_token": "e02cf1fa-75a5-48ab",
  "email_recipient": "reservations@hotel.com",
  "from": "sender@business.com",
  "recipient": "John S",
  "subject": "Hotel reservation",
  "template_token": "65452623-f049-49ea-8fcc-61ff039f4b50",
  "metadata": {
    "hotel_name": "Hilton",
    "total_days": "3"
  },
  "created_time": "2018-02-05 19:43:49",
  "last_modified_time": "2018-02-05 20:50:45",
  "transmission_outbounds": [
    {
      "state": "SENT",
      "link_expiration_time": "2018-02-05 20:43:54",
      "created_time": "2018-02-05 19:43:54",
      "last_modified_time": "2018-02-05 19:43:54"
    },
    {
      "state": "SENT",
      "link_expiration_time": "2018-02-05 21:50:42",
      "created_time": "2018-02-05 20:50:42",
      "last_modified_time": "2018-02-05 20:50:42"
    }
  ],
  "transmission_attempt_count": 2
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.