# Export Contacts

## Operation overview

```json
{"path":"https://api.sendgrid.com/v3/marketing/contacts/exports","method":"post","servers":[{"url":"https://api.sendgrid.com","description":"The Twilio SendGrid v3 API"}]}
```

**Use this endpoint to export lists or segments of contacts**.

If you would just like to have a link to the exported list sent to your email set the `notifications.email` option to `true` in the `POST` payload.

If you would like to download the list, take the `id` that is returned and use the "Export Contacts Status" endpoint to get the `urls`. Once you have the list of URLs, make a `GET` request to each URL provided to download your CSV file(s).

You specify the segments and or/contact lists you wish to export by providing the relevant IDs in, respectively, the `segment_ids` and `list_ids` fields in the request body.

The lists will be provided in either JSON or CSV files. To specify which of these you would required, set the request body `file_type` field to `json` or `csv`.

You can also specify a maximum file size (in MB). If the export file is larger than this, it will be split into multiple files.

## Operation details

### Authentication

API Key

### Headers

```json
[{"in":"header","name":"Authorization","required":true,"default":"Bearer <<YOUR_API_KEY_HERE>>","schema":{"type":"string"}}]
```

### Request body

```json
{"schema":{"type":"object","properties":{"list_ids":{"description":"IDs of the contact lists you want to export.","type":"array","items":{"type":"string","format":"uuid"}},"segment_ids":{"description":"IDs of the contact segments you want to export.","type":"array","items":{"type":"string"}},"notifications":{"type":"object","properties":{"email":{"type":"boolean"}}},"file_type":{"type":"string","description":"File type for export file. Choose from `json` or `csv`.","default":"csv","enum":["csv","json"],"refName":"FileType","modelName":"FileType"},"max_file_size":{"description":"The maximum size of an export file in MB. Note that when this option is specified, multiple output files may be returned from the export.","default":5000,"type":"integer"}}},"encodingType":"application/json"}
```

### Responses

```json
[{"responseCode":"202","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","required":["_metadata"],"properties":{"_metadata":{"title":"metadata","type":"object","refName":"Metadata","modelName":"Metadata","properties":{"prev":{"type":"string","format":"uri","description":"The URL of the previous page of results. If this field isn't present, you're at the start of the list."},"self":{"type":"string","format":"uri","description":"The URL of the current page of results."},"next":{"type":"string","format":"uri","description":"The URL of the next page of results. If this field isn't present, you're at the end of the list."},"count":{"type":"number","description":"The number of items in the entire list, i.e., across all pages."}}},"id":{"type":"string","description":"The ID of the export job."}}}}}}},{"responseCode":"400","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"title":"error","type":"object","example":{"field":"field_name","message":"error message"},"required":["message"],"refName":"ContactsError","modelName":"ContactsError","properties":{"message":{"type":"string"},"field":{"type":"string"},"error_id":{"type":"string"},"parameter":{"type":"string"}}}}}}}}}},{"responseCode":"401","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}}}},"refName":"#/components/responses/MarketingContacts401","modelName":"__components_responses_MarketingContacts401"}},{"responseCode":"403","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}}}},"refName":"#/components/responses/MarketingContacts403","modelName":"__components_responses_MarketingContacts403"}},{"responseCode":"404","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}}}},"refName":"#/components/responses/MarketingContacts404","modelName":"__components_responses_MarketingContacts404"}},{"responseCode":"500","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"refName":"#/components/responses/MarketingContacts500","modelName":"__components_responses_MarketingContacts500"}}]
```

Export Contacts

```js
const client = require("@sendgrid/client");
client.setApiKey(process.env.SENDGRID_API_KEY);

const request = {
  url: `/v3/marketing/contacts/exports`,
  method: "POST",
};

client
  .request(request)
  .then(([response, body]) => {
    console.log(response.statusCode);
    console.log(response.body);
  })
  .catch((error) => {
    console.error(error);
  });
```

```python
import os
from sendgrid import SendGridAPIClient


sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY"))


response = sg.client.marketing.contacts.exports.post()

print(response.status_code)
print(response.body)
print(response.headers)
```

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SendGrid;

public class Program {
    public static async Task Main() {
        string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
        var client = new SendGridClient(apiKey);

        var response = await client.RequestAsync(
            method: SendGridClient.Method.POST, urlPath: "marketing/contacts/exports");

        Console.WriteLine(response.StatusCode);
        Console.WriteLine(response.Body.ReadAsStringAsync().Result);
        Console.WriteLine(response.Headers.ToString());
    }
}
```

```java
import com.sendgrid.*;
import java.io.IOException;

public class Example {
    public static void main(String[] args) throws IOException {
        try {
            SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
            Request request = new Request();
            request.setMethod(Method.POST);
            request.setEndpoint("/marketing/contacts/exports");
            Response response = sg.api(request);
            System.out.println(response.getStatusCode());
            System.out.println(response.getBody());
            System.out.println(response.getHeaders());
        } catch (IOException ex) {
            throw ex;
        }
    }
}
```

```go
package main

import (
	"fmt"
	"github.com/sendgrid/sendgrid-go"
	"os"
)

func main() {
	apiKey := os.Getenv("SENDGRID_API_KEY")
	host := "https://api.sendgrid.com"
	request := sendgrid.GetRequest(apiKey, "/v3/marketing/contacts/exports", host)
	request.Method = "POST"
	response, err := sendgrid.API(request)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		fmt.Println(response.StatusCode)
		fmt.Println(response.Body)
		fmt.Println(response.Headers)
	}
}
```

```php
<?php
// Uncomment the next line if you're using a dependency loader (such as Composer) (recommended)
// require 'vendor/autoload.php';

// Uncomment next line if you're not using a dependency loader (such as Composer)
// require_once '<PATH TO>/sendgrid-php.php';

$apiKey = getenv("SENDGRID_API_KEY");
$sg = new \SendGrid($apiKey);

try {
    $response = $sg->client
        ->marketing()
        ->contacts()
        ->exports()
        ->post();
    print $response->statusCode() . "\n";
    print_r($response->headers());
    print $response->body() . "\n";
} catch (Exception $ex) {
    echo "Caught exception: " . $ex->getMessage();
}
```

```ruby
require 'sendgrid-ruby'
include SendGrid

sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])

response = sg.client.marketing.contacts.exports.post()
puts response.status_code
puts response.headers
puts response.body
```

```bash
curl -X POST "https://api.sendgrid.com/v3/marketing/contacts/exports" \
--header "Authorization: Bearer $SENDGRID_API_KEY"
```